[refactor] group the built-in conventions (#80957)

huozhi · web-flow · commit 71cdce68e02c · 2025-06-26T23:36:57.000+02:00
Group all the built-in conventions into `src/client/components/builtin` with the actual same name of the conventions they represent. e.g. The default `not-found.js` is `next/dist/client/compoents/builtin/not-found.js`; The default `global-error.js` is `next/dist/client/compoents/builtin/global-error.js`; This give us an easier way to track all the builtin conventions. This is also the preparation work for #80961 where we display the builtin conventions in the segment explorer.
diff --git a/crates/next-core/src/app_structure.rs b/crates/next-core/src/app_structure.rs
@@ -910,23 +910,23 @@ async fn directory_tree_to_loader_tree_internal(
         if modules.not_found.is_none() {
             modules.not_found = Some(
                 get_next_package(app_dir)
-                    .join(rcstr!("dist/client/components/not-found-error.js"))
+                    .join(rcstr!("dist/client/components/builtin/not-found.js"))
                     .to_resolved()
                     .await?,
             );
         }
         if modules.forbidden.is_none() {
             modules.forbidden = Some(
                 get_next_package(app_dir)
-                    .join(rcstr!("dist/client/components/forbidden-error.js"))
+                    .join(rcstr!("dist/client/components/builtin/forbidden.js"))
                     .to_resolved()
                     .await?,
             );
         }
         if modules.unauthorized.is_none() {
             modules.unauthorized = Some(
                 get_next_package(app_dir)
-                    .join(rcstr!("dist/client/components/unauthorized-error.js"))
+                    .join(rcstr!("dist/client/components/builtin/unauthorized.js"))
                     .to_resolved()
                     .await?,
             );
@@ -1130,7 +1130,7 @@ async fn default_route_tree(
             AppDirModules {
                 default: Some(
                     get_next_package(app_dir)
-                        .join(rcstr!("dist/client/components/parallel-route-default.js"))
+                        .join(rcstr!("dist/client/components/builtin/default.js"))
                         .to_resolved()
                         .await?,
                 ),
@@ -1275,7 +1275,7 @@ async fn directory_tree_to_entrypoints_internal_untraced(
         if modules.layout.is_none() {
             modules.layout = Some(
                 get_next_package(*app_dir)
-                    .join(rcstr!("dist/client/components/default-layout.js"))
+                    .join(rcstr!("dist/client/components/builtin/layout.js"))
                     .to_resolved()
                     .await?,
             );
@@ -1284,23 +1284,23 @@ async fn directory_tree_to_entrypoints_internal_untraced(
         if modules.not_found.is_none() {
             modules.not_found = Some(
                 get_next_package(*app_dir)
-                    .join(rcstr!("dist/client/components/not-found-error.js"))
+                    .join(rcstr!("dist/client/components/builtin/not-found.js"))
                     .to_resolved()
                     .await?,
             );
         }
         if modules.forbidden.is_none() {
             modules.forbidden = Some(
                 get_next_package(*app_dir)
-                    .join(rcstr!("dist/client/components/forbidden-error.js"))
+                    .join(rcstr!("dist/client/components/builtin/forbidden.js"))
                     .to_resolved()
                     .await?,
             );
         }
         if modules.unauthorized.is_none() {
             modules.unauthorized = Some(
                 get_next_package(*app_dir)
-                    .join(rcstr!("dist/client/components/unauthorized-error.js"))
+                    .join(rcstr!("dist/client/components/builtin/unauthorized.js"))
                     .to_resolved()
                     .await?,
             );
@@ -1335,7 +1335,7 @@ async fn directory_tree_to_entrypoints_internal_untraced(
                                     page: match modules.global_not_found {
                                         Some(v) => Some(v),
                                         None => Some(get_next_package(*app_dir)
-                                            .join(rcstr!("dist/client/components/global-not-found.js"))
+                                            .join(rcstr!("dist/client/components/builtin/global-not-found.js"))
                                             .to_resolved()
                                             .await?),
                                     },
@@ -1348,7 +1348,7 @@ async fn directory_tree_to_entrypoints_internal_untraced(
                                     page: match modules.not_found {
                                         Some(v) => Some(v),
                                         None => Some(get_next_package(*app_dir)
-                                            .join(rcstr!("dist/client/components/not-found-error.js"))
+                                            .join(rcstr!("dist/client/components/builtin/not-found.js"))
                                             .to_resolved()
                                             .await?),
                                     },
diff --git a/crates/next-core/src/next_app/app_page_entry.rs b/crates/next-core/src/next_app/app_page_entry.rs
@@ -88,7 +88,7 @@ pub async fn get_app_page_entry(
             "VAR_MODULE_GLOBAL_ERROR" => if inner_assets.contains_key(GLOBAL_ERROR) {
                 GLOBAL_ERROR.into()
              } else {
-                "next/dist/client/components/global-error".into()
+                "next/dist/client/components/builtin/global-error".into()
             },
         },
         fxindexmap! {
diff --git a/packages/next/src/build/entries.ts b/packages/next/src/build/entries.ts
@@ -305,7 +305,7 @@ export async function createPagesMapping({
         // If there's any custom /_not-found page, it will override the default one.
         ...(hasAppPages && {
           [UNDERSCORE_NOT_FOUND_ROUTE_ENTRY]: require.resolve(
-            'next/dist/client/components/global-not-found'
+            'next/dist/client/components/builtin/global-not-found'
           ),
         }),
         ...pages,
diff --git a/packages/next/src/build/index.ts b/packages/next/src/build/index.ts
@@ -1884,7 +1884,7 @@ export default async function build(
 
                 const pageFilePath = isAppBuiltinNotFoundPage(pagePath)
                   ? require.resolve(
-                      'next/dist/client/components/not-found-error'
+                      'next/dist/client/components/builtin/not-found'
                     )
                   : path.join(
                       (pageType === 'pages' ? pagesDir : appDir) || '',
diff --git a/packages/next/src/build/utils.ts b/packages/next/src/build/utils.ts
@@ -1756,7 +1756,7 @@ export function isReservedPage(page: string) {
 }
 
 export function isAppBuiltinNotFoundPage(page: string) {
-  return /next[\\/]dist[\\/]client[\\/]components[\\/](not-found-error|global-not-found)/.test(
+  return /next[\\/]dist[\\/]client[\\/]components[\\/]builtin[\\/](not-found|global-not-found)/.test(
     page
   )
 }
diff --git a/packages/next/src/build/webpack/loaders/next-app-loader/index.ts b/packages/next/src/build/webpack/loaders/next-app-loader/index.ts
@@ -30,7 +30,7 @@ import {
 } from '../../../../shared/lib/segment'
 import { getFilesInDir } from '../../../../lib/get-files-in-dir'
 import type { PageExtensions } from '../../../page-extensions-type'
-import { PARALLEL_ROUTE_DEFAULT_PATH } from '../../../../client/components/parallel-route-default'
+import { PARALLEL_ROUTE_DEFAULT_PATH } from '../../../../client/components/builtin/default'
 import type { Compilation } from 'webpack'
 import { createAppRouteCode } from './create-app-route-code'
 
@@ -59,9 +59,9 @@ const HTTP_ACCESS_FALLBACKS = {
   unauthorized: 'unauthorized',
 } as const
 const defaultHTTPAccessFallbackPaths = {
-  'not-found': 'next/dist/client/components/not-found-error',
-  forbidden: 'next/dist/client/components/forbidden-error',
-  unauthorized: 'next/dist/client/components/unauthorized-error',
+  'not-found': 'next/dist/client/components/builtin/not-found.js',
+  forbidden: 'next/dist/client/components/builtin/forbidden.js',
+  unauthorized: 'next/dist/client/components/builtin/unauthorized.js',
 } as const
 
 const FILE_TYPES = {
@@ -79,11 +79,12 @@ const GLOBAL_NOT_FOUND_FILE_TYPE = 'global-not-found'
 const PAGE_SEGMENT = 'page$'
 const PARALLEL_CHILDREN_SEGMENT = 'children$'
 
-const defaultGlobalErrorPath = 'next/dist/client/components/global-error.js'
-const defaultNotFoundPath = 'next/dist/client/components/not-found-error.js'
-const defaultLayoutPath = 'next/dist/client/components/default-layout.js'
+const defaultGlobalErrorPath =
+  'next/dist/client/components/builtin/global-error.js'
+const defaultNotFoundPath = 'next/dist/client/components/builtin/not-found.js'
+const defaultLayoutPath = 'next/dist/client/components/builtin/layout.js'
 const defaultGlobalNotFoundPath =
-  'next/dist/client/components/global-not-found.js'
+  'next/dist/client/components/builtin/global-not-found.js'
 
 type DirResolver = (pathToResolve: string) => string
 type PathResolver = (
diff --git a/packages/next/src/client/components/app-router-instance.ts b/packages/next/src/client/components/app-router-instance.ts
@@ -27,7 +27,7 @@ import type {
 import { setLinkForCurrentNavigation, type LinkInstance } from './links'
 import type { FlightRouterState } from '../../server/app-render/types'
 import type { ClientInstrumentationHooks } from '../app-index'
-import type { GlobalErrorComponent } from './global-error'
+import type { GlobalErrorComponent } from './builtin/global-error'
 
 export type DispatchStatePromise = React.Dispatch<ReducerState>
 
diff --git a/packages/next/src/client/components/app-router.tsx b/packages/next/src/client/components/app-router.tsx
@@ -23,7 +23,7 @@ import {
 } from '../../shared/lib/hooks-client-context.shared-runtime'
 import { dispatchAppRouterAction, useActionQueue } from './use-action-queue'
 import { ErrorBoundary } from './error-boundary'
-import DefaultGlobalError from '../../client/components/global-error'
+import DefaultGlobalError from './builtin/global-error'
 import { isBot } from '../../shared/lib/router/utils/is-bot'
 import { addBasePath } from '../add-base-path'
 import { AppRouterAnnouncer } from './app-router-announcer'
diff --git a/packages/next/src/client/components/builtin/default.tsx b/packages/next/src/client/components/builtin/default.tsx
@@ -1,7 +1,7 @@
-import { notFound } from './not-found'
+import { notFound } from '../not-found'
 
 export const PARALLEL_ROUTE_DEFAULT_PATH =
-  'next/dist/client/components/parallel-route-default.js'
+  'next/dist/client/components/builtin/default.js'
 
 export default function ParallelRouteDefault() {
   notFound()
diff --git a/packages/next/src/client/components/builtin/forbidden.tsx b/packages/next/src/client/components/builtin/forbidden.tsx
@@ -1,4 +1,4 @@
-import { HTTPAccessErrorFallback } from './http-access-fallback/error-fallback'
+import { HTTPAccessErrorFallback } from '../http-access-fallback/error-fallback'
 
 export default function Forbidden() {
   return (
diff --git a/packages/next/src/client/components/builtin/global-error.tsx b/packages/next/src/client/components/builtin/global-error.tsx
@@ -1,6 +1,6 @@
 'use client'
 
-import { HandleISRError } from './handle-isr-error'
+import { HandleISRError } from '../handle-isr-error'
 
 const styles = {
   error: {
diff --git a/packages/next/src/client/components/builtin/global-not-found.tsx b/packages/next/src/client/components/builtin/global-not-found.tsx
@@ -1,4 +1,4 @@
-import { HTTPAccessErrorFallback } from './http-access-fallback/error-fallback'
+import { HTTPAccessErrorFallback } from '../http-access-fallback/error-fallback'
 
 function GlobalNotFound() {
   return (
diff --git a/packages/next/src/client/components/builtin/layout.tsx b/packages/next/src/client/components/builtin/layout.tsx
diff --git a/packages/next/src/client/components/builtin/not-found.tsx b/packages/next/src/client/components/builtin/not-found.tsx
@@ -1,4 +1,4 @@
-import { HTTPAccessErrorFallback } from './http-access-fallback/error-fallback'
+import { HTTPAccessErrorFallback } from '../http-access-fallback/error-fallback'
 
 export default function NotFound() {
   return (
diff --git a/packages/next/src/client/components/builtin/unauthorized.tsx b/packages/next/src/client/components/builtin/unauthorized.tsx
@@ -1,4 +1,4 @@
-import { HTTPAccessErrorFallback } from './http-access-fallback/error-fallback'
+import { HTTPAccessErrorFallback } from '../http-access-fallback/error-fallback'
 
 export default function Unauthorized() {
   return (
diff --git a/packages/next/src/client/react-client-callbacks/error-boundary-callbacks.ts b/packages/next/src/client/react-client-callbacks/error-boundary-callbacks.ts
@@ -12,7 +12,7 @@ import { isBailoutToCSRError } from '../../shared/lib/lazy-dynamic/bailout-to-cs
 import { reportGlobalError } from './report-global-error'
 import { originConsoleError } from '../../next-devtools/userspace/app/errors/intercept-console-error'
 import { ErrorBoundaryHandler } from '../components/error-boundary'
-import DefaultErrorBoundary from '../components/global-error'
+import DefaultErrorBoundary from '../components/builtin/global-error'
 
 export function onCaughtError(
   thrownValue: unknown,
diff --git a/packages/next/src/next-devtools/userspace/app/app-dev-overlay-error-boundary.tsx b/packages/next/src/next-devtools/userspace/app/app-dev-overlay-error-boundary.tsx
@@ -2,7 +2,7 @@ import { PureComponent } from 'react'
 import { dispatcher } from 'next/dist/compiled/next-devtools'
 import { RuntimeErrorHandler } from '../../../client/dev/runtime-error-handler'
 import { ErrorBoundary } from '../../../client/components/error-boundary'
-import DefaultGlobalError from '../../../client/components/global-error'
+import DefaultGlobalError from '../../../client/components/builtin/global-error'
 import type { GlobalErrorState } from '../../../client/components/app-router-instance'
 
 type AppDevOverlayErrorBoundaryProps = {
diff --git a/packages/next/src/next-devtools/userspace/app/client-entry.tsx b/packages/next/src/next-devtools/userspace/app/client-entry.tsx
@@ -1,7 +1,7 @@
 import React from 'react'
 import { getSocketUrl } from '../../../client/dev/hot-reloader/get-socket-url'
 import { HMR_ACTIONS_SENT_TO_BROWSER } from '../../../server/dev/hot-reloader-types'
-import DefaultGlobalError from '../../../client/components/global-error'
+import DefaultGlobalError from '../../../client/components/builtin/global-error'
 import { AppDevOverlayErrorBoundary } from './app-dev-overlay-error-boundary'
 
 // if an error is thrown while rendering an RSC stream, this will catch it in dev
diff --git a/packages/next/src/server/app-render/app-render.tsx b/packages/next/src/server/app-render/app-render.tsx
@@ -199,7 +199,7 @@ import {
   trackPendingModules,
 } from './module-loading/track-module-loading.external'
 import { isReactLargeShellError } from './react-large-shell-error'
-import type { GlobalErrorComponent } from '../../client/components/global-error'
+import type { GlobalErrorComponent } from '../../client/components/builtin/global-error'
 
 export type GetDynamicParamFromSegment = (
   // [slug] / [[slug]] / [...slug]
diff --git a/packages/next/src/server/app-render/create-component-tree.tsx b/packages/next/src/server/app-render/create-component-tree.tsx
@@ -13,7 +13,7 @@ import { createComponentStylesAndScripts } from './create-component-styles-and-s
 import { getLayerAssets } from './get-layer-assets'
 import { hasLoadingComponentInTree } from './has-loading-component-in-tree'
 import { validateRevalidate } from '../lib/patch-fetch'
-import { PARALLEL_ROUTE_DEFAULT_PATH } from '../../client/components/parallel-route-default'
+import { PARALLEL_ROUTE_DEFAULT_PATH } from '../../client/components/builtin/default'
 import { getTracer } from '../lib/trace/tracer'
 import { NextNodeServerSpan } from '../lib/trace/constants'
 import { StaticGenBailoutError } from '../../client/components/static-generation-bailout'
@@ -1109,7 +1109,7 @@ export function normalizeConventionFilePath(
 ) {
   const cwd = process.env.NEXT_RUNTIME === 'edge' ? '' : process.cwd()
   const nextInternalPrefixRegex =
-    /^(.*[\\/])?next[\\/]dist[\\/]client[\\/]components[\\/]/
+    /^(.*[\\/])?next[\\/]dist[\\/]client[\\/]components[\\/]builtin[\\/]/
 
   let relativePath = (conventionPath || '')
     // remove turbopack [project] prefix
diff --git a/packages/next/src/server/app-render/entry-base.ts b/packages/next/src/server/app-render/entry-base.ts
@@ -33,7 +33,7 @@ import { patchFetch as _patchFetch } from '../lib/patch-fetch'
 // * ErrorBoundary -> client/components/error-boundary
 // * GlobalError -> client/components/global-error
 import '../../client/components/error-boundary'
-import '../../client/components/global-error'
+import '../../client/components/builtin/global-error'
 import {
   MetadataBoundary,
   ViewportBoundary,
diff --git a/packages/next/src/server/dev/on-demand-entry-handler.ts b/packages/next/src/server/dev/on-demand-entry-handler.ts
@@ -473,7 +473,7 @@ export async function findPagePathData(
       // If they're not presented, then fallback to global-not-found
       return {
         filename: require.resolve(
-          'next/dist/client/components/global-not-found'
+          'next/dist/client/components/builtin/global-not-found'
         ),
         bundlePath: `app${UNDERSCORE_NOT_FOUND_ROUTE_ENTRY}`,
         page: UNDERSCORE_NOT_FOUND_ROUTE_ENTRY,
diff --git a/test/development/app-dir/segment-explorer/segment-explorer.test.ts b/test/development/app-dir/segment-explorer/segment-explorer.test.ts
@@ -120,7 +120,7 @@ describe('segment-explorer', () => {
     expect(await getSegmentExplorerContent(browser)).toMatchInlineSnapshot(`
      "app/
      layout.tsx
-     not-found-error.js"
+     not-found.js"
     `)
   })
 

Original file line number	Diff line number	Diff line change
`@@ -1884,7 +1884,7 @@ export default async function build(`
`1884`	`1884`
`1885`	`1885`	`const pageFilePath = isAppBuiltinNotFoundPage(pagePath)`
`1886`	`1886`	`? require.resolve(`
`1887`		`- 'next/dist/client/components/not-found-error'`
	`1887`	`+ 'next/dist/client/components/builtin/not-found'`
`1888`	`1888`	`)`
`1889`	`1889`	`: path.join(`
`1890`	`1890`	`(pageType === 'pages' ? pagesDir : appDir) \|\| '',`
Original file line number	Diff line number	Diff line change
`@@ -1756,7 +1756,7 @@ export function isReservedPage(page: string) {`
`1756`	`1756`	`}`
`1757`	`1757`
`1758`	`1758`	`export function isAppBuiltinNotFoundPage(page: string) {`
`1759`		`- return /next[\\/]dist[\\/]client[\\/]components[\\/](not-found-error\|global-not-found)/.test(`
	`1759`	`+ return /next[\\/]dist[\\/]client[\\/]components[\\/]builtin[\\/](not-found\|global-not-found)/.test(`
`1760`	`1760`	`page`
`1761`	`1761`	`)`
`1762`	`1762`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import { HTTPAccessErrorFallback } from './http-access-fallback/error-fallback'`
	`1`	`+import { HTTPAccessErrorFallback } from '../http-access-fallback/error-fallback'`
`2`	`2`
`3`	`3`	`export default function Forbidden() {`
`4`	`4`	`return (`