Introduce Forbidden and the UI Error abstraction

packages/next/src/build/webpack/loaders/next-app-loader.ts

@@ -55,19 +55,32 @@ export type AppLoaderOptions = {
 }
 type AppLoader = webpack.LoaderDefinitionFunction<AppLoaderOptions>
 
+const UI_FILE_TYPES = {
+  'not-found': 'not-found',
+  forbidden: 'forbidden',
+} as const
+
+type UIFileType = keyof typeof UI_FILE_TYPES
+
+const UI_FILE_TYPES_AS_VALUES = Object.keys(UI_FILE_TYPES) as UIFileType[]
+
 const FILE_TYPES = {
   layout: 'layout',
   template: 'template',
   error: 'error',
   loading: 'loading',
-  'not-found': 'not-found',
+  ...UI_FILE_TYPES,
 } as const
 
 const GLOBAL_ERROR_FILE_TYPE = 'global-error'
 const PAGE_SEGMENT = 'page$'
 const PARALLEL_CHILDREN_SEGMENT = 'children$'
 
-const defaultNotFoundPath = 'next/dist/client/components/not-found-error'
+const defaultUIErrorPaths: Record<UIFileType, string> = {
+  'not-found': 'next/dist/client/components/not-found-error',
+  forbidden: 'next/dist/client/components/forbidden-error',
+}
+
 const defaultGlobalErrorPath = 'next/dist/client/components/error-boundary'
 const defaultLayoutPath = 'next/dist/client/components/default-layout'
 
@@ -200,9 +213,13 @@ async function createTreeCodeFromPath(
 
   const isDefaultNotFound = isAppBuiltinNotFoundPage(pagePath)
   const appDirPrefix = isDefaultNotFound ? APP_DIR_ALIAS : splittedPath[0]
-  const hasRootNotFound = await resolver(
-    `${appDirPrefix}/${FILE_TYPES['not-found']}`
+
+  const uiErrorPaths = await Promise.all(
+    UI_FILE_TYPES_AS_VALUES.map((fileType) =>
+      resolver(`${appDirPrefix}/${UI_FILE_TYPES[fileType]}`)
+    )
   )
+
   const pages: string[] = []
 
   let rootLayout: string | undefined
@@ -354,18 +371,45 @@ async function createTreeCodeFromPath(
         ([, filePath]) => filePath !== undefined
       ) as [ValueOf<typeof FILE_TYPES>, string][]
 
-      // Add default not found error as root not found if not present
-      const hasNotFoundFile = definedFilePaths.some(
-        ([type]) => type === 'not-found'
+      // Mark used ui error files by the route segment
+      function createFileTypeCounters(
+        paths: typeof filePaths,
+        types: UIFileType[]
+      ) {
+        const dictionary = new Map<string, number>()
+        for (const [type] of paths) {
+          const item = dictionary.get(type)
+          if (item) {
+            dictionary.set(type, item + 1)
+          } else {
+            dictionary.set(type, 1)
+          }
+        }
+
+        return types.map((t) => (dictionary.get(t) || 0) >= 1)
+      }
+
+      // Check if ui error files exist for this segment path
+      const fileTypeCounters = createFileTypeCounters(
+        definedFilePaths,
+        UI_FILE_TYPES_AS_VALUES
       )
+
       // If the first layer is a group route, we treat it as root layer
       const isFirstLayerGroupRoute =
         segments.length === 1 &&
         subSegmentPath.filter((seg) => isGroupSegment(seg)).length === 1
-      if ((isRootLayer || isFirstLayerGroupRoute) && !hasNotFoundFile) {
-        // If you already have a root not found, don't insert default not-found to group routes root
-        if (!(hasRootNotFound && isFirstLayerGroupRoute)) {
-          definedFilePaths.push(['not-found', defaultNotFoundPath])
+
+      for (let i = 0; i < UI_FILE_TYPES_AS_VALUES.length; i++) {
+        const fileType = UI_FILE_TYPES_AS_VALUES[i]
+        const hasFileType = fileTypeCounters[i]
+        const hasRootFileType = uiErrorPaths[i]
+
+        if ((isRootLayer || isFirstLayerGroupRoute) && !hasFileType) {
+          // If you already have a root file, don't insert default file to group routes root
+          if (!(hasRootFileType && isFirstLayerGroupRoute)) {
+            definedFilePaths.push([fileType, defaultUIErrorPaths[fileType]])
+          }
         }
       }
 
@@ -410,7 +454,7 @@ async function createTreeCodeFromPath(
       if (isNotFoundRoute && normalizedParallelKey === 'children') {
         const notFoundPath =
           definedFilePaths.find(([type]) => type === 'not-found')?.[1] ??
-          defaultNotFoundPath
+          defaultUIErrorPaths['not-found']
 
         const varName = `notFound${nestedCollectedDeclarations.length}`
         nestedCollectedDeclarations.push([varName, notFoundPath])

packages/next/src/client/components/app-router.tsx

@@ -687,14 +687,14 @@ function Router({
 
   if (process.env.NODE_ENV !== 'production') {
     if (typeof window !== 'undefined') {
-      const DevRootNotFoundBoundary: typeof import('./dev-root-not-found-boundary').DevRootNotFoundBoundary =
-        require('./dev-root-not-found-boundary').DevRootNotFoundBoundary
+      const DevRootUIErrorsBoundary: typeof import('./dev-root-ui-error-boundary').DevRootUIErrorsBoundary =
+        require('./dev-root-ui-error-boundary').DevRootUIErrorsBoundary
       content = (
-        <DevRootNotFoundBoundary>
+        <DevRootUIErrorsBoundary>
           <MissingSlotContext.Provider value={missingSlots}>
             {content}
           </MissingSlotContext.Provider>
-        </DevRootNotFoundBoundary>
+        </DevRootUIErrorsBoundary>
       )
     }
     const HotReloader: typeof import('./react-dev-overlay/app/hot-reloader-client').default =

packages/next/src/client/components/dev-root-ui-error-boundary.tsx

@@ -0,0 +1,33 @@
+'use client'
+
+import React from 'react'
+import { ForbiddenBoundary, NotFoundBoundary } from './ui-errors-boundaries'
+import type { UIErrorHelper } from '../../shared/lib/ui-error-types'
+
+export function bailOnUIError(uiError: UIErrorHelper) {
+  throw new Error(`${uiError}() is not allowed to use in root layout`)
+}
+
+function NotAllowedRootNotFoundError() {
+  bailOnUIError('notFound')
+  return null
+}
+
+function NotAllowedRootForbiddenError() {
+  bailOnUIError('forbidden')
+  return null
+}
+
+export function DevRootUIErrorsBoundary({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <ForbiddenBoundary uiComponent={<NotAllowedRootForbiddenError />}>
+      <NotFoundBoundary uiComponent={<NotAllowedRootNotFoundError />}>
+        {children}
+      </NotFoundBoundary>
+    </ForbiddenBoundary>
+  )
+}

packages/next/src/client/components/forbidden-error.tsx

@@ -0,0 +1,11 @@
+import { UIErrorTemplate } from './ui-error-template'
+
+export default function Forbidden() {
+  return (
+    <UIErrorTemplate
+      pageTitle="403: This page is forbidden."
+      title="403"
+      subtitle="This page is forbidden."
+    />
+  )
+}

packages/next/src/client/components/forbidden.ts

@@ -0,0 +1,33 @@
+import { createUIError } from './ui-error-builder'
+
+const { thrower, matcher } = createUIError('NEXT_FORBIDDEN')
+
+// TODO(@panteliselef): Update docs
+/**
+ * This function allows you to render the [forbidden.js file]
+ * within a route segment as well as inject a tag.
+ *
+ * `forbidden()` can be used in
+ * [Server Components](https://nextjs.org/docs/app/building-your-application/rendering/server-components),
+ * [Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers), and
+ * [Server Actions](https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations).
+ *
+ * - In a Server Component, this will insert a `<meta name="robots" content="noindex" />` meta tag and set the status code to 403.
+ * - In a Route Handler or Server Action, it will serve a 403 to the caller.
+ *
+ * // TODO(@panteliselef): Update docs
+ * Read more: [Next.js Docs: `forbidden`](https://nextjs.org/docs/app/api-reference/functions/not-found)
+ */
+const forbidden = thrower
+
+// TODO(@panteliselef): Update docs
+/**
+ * Checks an error to determine if it's an error generated by the `forbidden()`
+ * helper.
+ *
+ * @param error the error that may reference a forbidden error
+ * @returns true if the error is a forbidden error
+ */
+const isForbiddenError = matcher
+
+export { forbidden, isForbiddenError }

packages/next/src/client/components/is-next-router-error.ts

@@ -1,8 +1,8 @@
-import { isNotFoundError } from './not-found'
 import { isRedirectError } from './redirect'
+import { matchUIError } from '../../shared/lib/ui-error-types'
 
 export function isNextRouterError(error: any): boolean {
   return (
-    error && error.digest && (isRedirectError(error) || isNotFoundError(error))
+    error && error.digest && (isRedirectError(error) || !!matchUIError(error))
   )
 }

packages/next/src/client/components/layout-router.tsx

@@ -32,10 +32,10 @@ import { ErrorBoundary } from './error-boundary'
 import { matchSegment } from './match-segments'
 import { handleSmoothScroll } from '../../shared/lib/router/utils/handle-smooth-scroll'
 import { RedirectBoundary } from './redirect-boundary'
-import { NotFoundBoundary } from './not-found-boundary'
 import { getSegmentValue } from './router-reducer/reducers/get-segment-value'
 import { createRouterCacheKey } from './router-reducer/create-router-cache-key'
 import { hasInterceptionRouteInCurrentTree } from './router-reducer/reducers/has-interception-route-in-current-tree'
+import { ForbiddenBoundary, NotFoundBoundary } from './ui-errors-boundaries'
 
 /**
  * Add refetch marker to router state at the point of the current layout segment.
@@ -546,6 +546,8 @@ export default function OuterLayoutRouter({
   template,
   notFound,
   notFoundStyles,
+  forbidden,
+  forbiddenStyles,
   styles,
 }: {
   parallelRouterKey: string
@@ -558,6 +560,8 @@ export default function OuterLayoutRouter({
   template: React.ReactNode
   notFound: React.ReactNode | undefined
   notFoundStyles: React.ReactNode | undefined
+  forbidden: React.ReactNode | undefined
+  forbiddenStyles: React.ReactNode | undefined
   styles?: React.ReactNode
 }) {
   const context = useContext(LayoutRouterContext)
@@ -621,24 +625,29 @@ export default function OuterLayoutRouter({
                     loadingStyles={loading?.[1]}
                     loadingScripts={loading?.[2]}
                   >
-                    <NotFoundBoundary
-                      notFound={notFound}
-                      notFoundStyles={notFoundStyles}
+                    <ForbiddenBoundary
+                      uiComponent={forbidden}
+                      uiComponentStyles={forbiddenStyles}
                     >
-                      <RedirectBoundary>
-                        <InnerLayoutRouter
-                          parallelRouterKey={parallelRouterKey}
-                          url={url}
-                          tree={tree}
-                          childNodes={childNodesForParallelRouter!}
-                          segmentPath={segmentPath}
-                          cacheKey={cacheKey}
-                          isActive={
-                            currentChildSegmentValue === preservedSegmentValue
-                          }
-                        />
-                      </RedirectBoundary>
-                    </NotFoundBoundary>
+                      <NotFoundBoundary
+                        uiComponent={notFound}
+                        uiComponentStyles={notFoundStyles}
+                      >
+                        <RedirectBoundary>
+                          <InnerLayoutRouter
+                            parallelRouterKey={parallelRouterKey}
+                            url={url}
+                            tree={tree}
+                            childNodes={childNodesForParallelRouter!}
+                            segmentPath={segmentPath}
+                            cacheKey={cacheKey}
+                            isActive={
+                              currentChildSegmentValue === preservedSegmentValue
+                            }
+                          />
+                        </RedirectBoundary>
+                      </NotFoundBoundary>
+                    </ForbiddenBoundary>
                   </LoadingBoundary>
                 </ErrorBoundary>
               </ScrollAndFocusHandler>

packages/next/src/client/components/navigation.react-server.ts

@@ -28,5 +28,6 @@ class ReadonlyURLSearchParams extends URLSearchParams {
 
 export { redirect, permanentRedirect, RedirectType } from './redirect'
 export { notFound } from './not-found'
+export { forbidden } from './forbidden'
 export { unstable_rethrow } from './unstable-rethrow'
 export { ReadonlyURLSearchParams }

packages/next/src/client/components/navigation.ts

@@ -261,6 +261,7 @@ export function useSelectedLayoutSegment(
 // Shared components APIs
 export {
   notFound,
+  forbidden,
   redirect,
   permanentRedirect,
   RedirectType,