[not-found] Add global-not-found convention (vercel#78783)

### Feature

Introducing a new convention `global-not-found.js`, which let you build your own 404 page within app router. This convention is similar to `global-error.js` but for not found in general case, it's similar to `not-found.js` but including the layout.

App router has an implicit convention of building the 404 route, which is composing the top-level root `layout.js` and the root `not-found.js` to build up a 404 page. Since it's so implicit so that users don't have much control over it, which also lead to some confusing errors like `/_not-found` route is build failed due to various reason.

The `global-not-found.js` convention is aimed to help users to build 404 route in App Router easily and convenience. Currently it will be bound with a flag `experimental.globalNotFound` and later it will become the stable feature in next major release as it introduces a minor breaking change that we won't use root layout and root not-found to compose the 404 page. Instead, we'll either choose the builtin 404 page or users customized `global-not-found.js` to generate the 404 page when you enable the feature.

#### Advantages

Good new that if you were having struggles with creating 404 page for the multi root layouts app, such as the case below. Then `global-not-found.js` is your choose.

```
- (2024)/
   /layout.js
   /... # routes
- (2025)/
   /layout.js
   /... # routes
```

Closes NDX-1036
Related vercel#59180


#### Follow up

The metadata and deployment will be followed up in new PRs

Author: huozhi

crates/next-api/src/app.rs

@@ -194,7 +194,12 @@ impl AppProject {
 
     #[turbo_tasks::function]
     fn app_entrypoints(&self) -> Vc<AppEntrypoints> {
-        get_entrypoints(*self.app_dir, self.project.next_config().page_extensions())
+        let conf = self.project.next_config();
+        get_entrypoints(
+            *self.app_dir,
+            conf.page_extensions(),
+            conf.is_global_not_found_enabled(),
+        )
     }
 
     #[turbo_tasks::function]

crates/next-core/src/app_page_loader_tree.rs

@@ -335,6 +335,7 @@ impl AppPageLoaderTreeBuilder {
             default,
             error,
             global_error,
+            global_not_found,
             layout,
             loading,
             template,
@@ -375,6 +376,8 @@ impl AppPageLoaderTreeBuilder {
             .await?;
         self.write_modules_entry(AppDirModuleType::GlobalError, *global_error)
             .await?;
+        self.write_modules_entry(AppDirModuleType::GlobalNotFound, *global_not_found)
+            .await?;
 
         let modules_code = replace(&mut self.loader_tree_code, temp_loader_tree_code);
 
@@ -399,6 +402,7 @@ impl AppPageLoaderTreeBuilder {
         let loader_tree = &*loader_tree.await?;
 
         let modules = &loader_tree.modules;
+        // load global-error module
         if let Some(global_error) = modules.global_error {
             let module = self
                 .base
@@ -407,6 +411,17 @@ impl AppPageLoaderTreeBuilder {
                 .await?;
             self.base.inner_assets.insert(GLOBAL_ERROR.into(), module);
         };
+        // load global-not-found module
+        if let Some(global_not_found) = modules.global_not_found {
+            let module = self
+                .base
+                .process_source(Vc::upcast(FileSource::new(*global_not_found)))
+                .to_resolved()
+                .await?;
+            self.base
+                .inner_assets
+                .insert(GLOBAL_NOT_FOUND.into(), module);
+        };
 
         self.walk_tree(loader_tree, true).await?;
         Ok(AppPageLoaderTreeModule {
@@ -439,3 +454,4 @@ impl AppPageLoaderTreeModule {
 }
 
 pub const GLOBAL_ERROR: &str = "GLOBAL_ERROR_MODULE";
+pub const GLOBAL_NOT_FOUND: &str = "GLOBAL_NOT_FOUND_MODULE";

crates/next-core/src/app_structure.rs

@@ -39,6 +39,8 @@ pub struct AppDirModules {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub global_error: Option<ResolvedVc<FileSystemPath>>,
     #[serde(skip_serializing_if = "Option::is_none")]
+    pub global_not_found: Option<ResolvedVc<FileSystemPath>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub loading: Option<ResolvedVc<FileSystemPath>>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub template: Option<ResolvedVc<FileSystemPath>>,
@@ -63,6 +65,7 @@ impl AppDirModules {
             layout: self.layout,
             error: self.error,
             global_error: self.global_error,
+            global_not_found: self.global_not_found,
             loading: self.loading,
             template: self.template,
             not_found: self.not_found,
@@ -322,6 +325,7 @@ async fn get_directory_tree_internal(
                             "layout" => modules.layout = Some(file),
                             "error" => modules.error = Some(file),
                             "global-error" => modules.global_error = Some(file),
+                            "global-not-found" => modules.global_not_found = Some(file),
                             "loading" => modules.loading = Some(file),
                             "template" => modules.template = Some(file),
                             "forbidden" => modules.forbidden = Some(file),
@@ -730,11 +734,13 @@ fn add_app_metadata_route(
 pub fn get_entrypoints(
     app_dir: Vc<FileSystemPath>,
     page_extensions: Vc<Vec<RcStr>>,
+    is_global_not_found_enabled: Vc<bool>,
 ) -> Vc<Entrypoints> {
     directory_tree_to_entrypoints(
         app_dir,
         get_directory_tree(app_dir, page_extensions),
         get_global_metadata(app_dir, page_extensions),
+        is_global_not_found_enabled,
         Default::default(),
     )
 }
@@ -744,11 +750,13 @@ fn directory_tree_to_entrypoints(
     app_dir: Vc<FileSystemPath>,
     directory_tree: Vc<DirectoryTree>,
     global_metadata: Vc<GlobalMetadata>,
+    is_global_not_found_enabled: Vc<bool>,
     root_layouts: Vc<FileSystemPathVec>,
 ) -> Vc<Entrypoints> {
     directory_tree_to_entrypoints_internal(
         app_dir,
         global_metadata,
+        is_global_not_found_enabled,
         "".into(),
         directory_tree,
         AppPage::new(),
@@ -1124,6 +1132,7 @@ async fn default_route_tree(
 async fn directory_tree_to_entrypoints_internal(
     app_dir: ResolvedVc<FileSystemPath>,
     global_metadata: Vc<GlobalMetadata>,
+    is_global_not_found_enabled: Vc<bool>,
     directory_name: RcStr,
     directory_tree: Vc<DirectoryTree>,
     app_page: AppPage,
@@ -1133,6 +1142,7 @@ async fn directory_tree_to_entrypoints_internal(
     directory_tree_to_entrypoints_internal_untraced(
         app_dir,
         global_metadata,
+        is_global_not_found_enabled,
         directory_name,
         directory_tree,
         app_page,
@@ -1145,6 +1155,7 @@ async fn directory_tree_to_entrypoints_internal(
 async fn directory_tree_to_entrypoints_internal_untraced(
     app_dir: ResolvedVc<FileSystemPath>,
     global_metadata: Vc<GlobalMetadata>,
+    is_global_not_found_enabled: Vc<bool>,
     directory_name: RcStr,
     directory_tree: Vc<DirectoryTree>,
     app_page: AppPage,
@@ -1284,6 +1295,13 @@ async fn directory_tree_to_entrypoints_internal_untraced(
 
         // Next.js has this logic in "collect-app-paths", where the root not-found page
         // is considered as its own entry point.
+
+        // Determine if we enable the global not-found feature.
+        let is_global_not_found_enabled = *is_global_not_found_enabled.await?;
+        let use_global_not_found =
+            is_global_not_found_enabled || modules.global_not_found.is_some();
+
+        let not_found_root_modules = modules.without_leafs();
         let not_found_tree = AppPageLoaderTree {
             page: app_page.clone(),
             segment: directory_name.clone(),
@@ -1296,24 +1314,54 @@ async fn directory_tree_to_entrypoints_internal_untraced(
                             page: app_page.clone(),
                             segment: "__PAGE__".into(),
                             parallel_routes: FxIndexMap::default(),
-                            modules: AppDirModules {
-                                page: match modules.not_found {
-                                    Some(v) => Some(v),
-                                    None => Some(get_next_package(*app_dir)
-                                        .join("dist/client/components/not-found-error.js".into())
-                                        .to_resolved()
-                                        .await?),
-                                },
-                                ..Default::default()
+                            modules: if use_global_not_found {
+                                // if global-not-found.js is present:
+                                // we use it for the page and no layout, since layout is included in global-not-found.js;
+                                AppDirModules {
+                                    layout: None,
+                                    page: match modules.global_not_found {
+                                        Some(v) => Some(v),
+                                        None => Some(get_next_package(*app_dir)
+                                            .join("dist/client/components/global-not-found.js".into())
+                                            .to_resolved()
+                                            .await?),
+                                    },
+                                    ..Default::default()
+                                }
+                            } else {
+                                // if global-not-found.js is not present:
+                                // we search if we can compose root layout with the root not-found.js;
+                                AppDirModules {
+                                    page: match modules.not_found {
+                                        Some(v) => Some(v),
+                                        None => Some(get_next_package(*app_dir)
+                                            .join("dist/client/components/not-found-error.js".into())
+                                            .to_resolved()
+                                            .await?),
+                                    },
+                                    ..Default::default()
+                                }
                             },
                             global_metadata: global_metadata.to_resolved().await?,
                         }
                     },
-                    modules: AppDirModules::default(),
+                    modules: AppDirModules {
+                        ..Default::default()
+                    },
                     global_metadata: global_metadata.to_resolved().await?,
                 },
             },
-            modules: modules.without_leafs(),
+            modules: AppDirModules {
+                // `global-not-found.js` does not need a layout since it's included.
+                // Skip it if it's present.
+                // Otherwise, we need to compose it with the root layout to compose with not-found.js boundary.
+                layout: if use_global_not_found {
+                    None
+                } else {
+                    modules.layout
+                },
+                ..not_found_root_modules
+            },
             global_metadata: global_metadata.to_resolved().await?,
         }
         .resolved_cell();
@@ -1345,6 +1393,7 @@ async fn directory_tree_to_entrypoints_internal_untraced(
             let map = directory_tree_to_entrypoints_internal(
                 *app_dir,
                 global_metadata,
+                is_global_not_found_enabled,
                 subdir_name.clone(),
                 *subdirectory,
                 child_app_page.clone(),

crates/next-core/src/base_loader_tree.rs

@@ -32,6 +32,7 @@ pub enum AppDirModuleType {
     Forbidden,
     Unauthorized,
     GlobalError,
+    GlobalNotFound,
 }
 
 impl AppDirModuleType {
@@ -47,6 +48,7 @@ impl AppDirModuleType {
             AppDirModuleType::Forbidden => "forbidden",
             AppDirModuleType::Unauthorized => "unauthorized",
             AppDirModuleType::GlobalError => "global-error",
+            AppDirModuleType::GlobalNotFound => "global-not-found",
         }
     }
 }

crates/next-core/src/next_config.rs

@@ -799,6 +799,8 @@ pub struct ExperimentalConfig {
     turbopack_persistent_caching: Option<bool>,
     turbopack_source_maps: Option<bool>,
     turbopack_tree_shaking: Option<bool>,
+    // Whether to enable the global-not-found convention
+    global_not_found: Option<bool>,
 }
 
 #[derive(
@@ -1189,6 +1191,11 @@ impl NextConfig {
         Vc::cell(self.page_extensions.clone())
     }
 
+    #[turbo_tasks::function]
+    pub fn is_global_not_found_enabled(&self) -> Vc<bool> {
+        Vc::cell(self.experimental.global_not_found.unwrap_or_default())
+    }
+
     #[turbo_tasks::function]
     pub fn transpile_packages(&self) -> Vc<Vec<RcStr>> {
         Vc::cell(self.transpile_packages.clone().unwrap_or_default())

packages/next/src/build/entries.ts

@@ -301,11 +301,12 @@ export async function createPagesMapping({
         page.endsWith('/page')
       )
       return {
-        // If there's any app pages existed, add a default not-found page.
-        // If there's any custom not-found page existed, it will override the default one.
+        // If there's any app pages existed, add a default /_not-found route as 404.
+        // If there's any custom /_not-found page, it will override the default one.
         ...(hasAppPages && {
-          [UNDERSCORE_NOT_FOUND_ROUTE_ENTRY]:
-            'next/dist/client/components/not-found-error',
+          [UNDERSCORE_NOT_FOUND_ROUTE_ENTRY]: require.resolve(
+            'next/dist/client/components/global-not-found'
+          ),
         }),
         ...pages,
       }
@@ -720,6 +721,9 @@ export async function createEntrypoints(
                 : undefined,
               preferredRegion: staticInfo.preferredRegion,
               middlewareConfig: encodeToBase64(staticInfo.middleware || {}),
+              isGlobalNotFoundEnabled: config.experimental.globalNotFound
+                ? true
+                : undefined,
             })
           } else if (isInstrumentation) {
             server[serverBundlePath.replace('src/', '')] =
@@ -799,6 +803,9 @@ export async function createEntrypoints(
                 middlewareConfig: Buffer.from(
                   JSON.stringify(staticInfo.middleware || {})
                 ).toString('base64'),
+                isGlobalNotFoundEnabled: config.experimental.globalNotFound
+                  ? true
+                  : undefined,
               }).import
             }
             edgeServer[serverBundlePath] = getEdgeServerEntry({

packages/next/src/build/utils.ts

@@ -1751,7 +1751,7 @@ export function isReservedPage(page: string) {
 }
 
 export function isAppBuiltinNotFoundPage(page: string) {
-  return /next[\\/]dist[\\/]client[\\/]components[\\/]not-found-error/.test(
+  return /next[\\/]dist[\\/]client[\\/]components[\\/](not-found-error|global-not-found)/.test(
     page
   )
 }