[segment-explorer] display the builtin conventions (#80961)

Track built-in conventions in segment explorer. The default `global-not-found.js` and `global-error.js` will be displayed.
Their style will be different to the others, we'll follow up in the later PRs.

Closes NEXT-4576

Author: huozhi

crates/next-core/src/app_structure.rs

@@ -931,6 +931,14 @@ async fn directory_tree_to_loader_tree_internal(
                     .await?,
             );
         }
+        if modules.global_error.is_none() {
+            modules.global_error = Some(
+                get_next_package(app_dir)
+                    .join(rcstr!("dist/client/components/builtin/global-error.js"))
+                    .to_resolved()
+                    .await?,
+            );
+        }
     }
 
     let mut tree = AppPageLoaderTree {

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

@@ -159,8 +159,8 @@ async function createTreeCodeFromPath(
   const pages: string[] = []
 
   let rootLayout: string | undefined
-  let globalError: string | undefined
-  let globalNotFound: string | undefined
+  let globalError: string = defaultGlobalErrorPath
+  let globalNotFound: string = defaultNotFoundPath
 
   async function resolveAdjacentParallelSegments(
     segmentPath: string
@@ -303,6 +303,33 @@ async function createTreeCodeFromPath(
         })
       )
 
+      // Only resolve global-* convention files at the root layer
+      if (isRootLayer) {
+        const resolvedGlobalErrorPath = await resolver(
+          `${appDirPrefix}/${GLOBAL_ERROR_FILE_TYPE}`
+        )
+        if (resolvedGlobalErrorPath) {
+          globalError = resolvedGlobalErrorPath
+        }
+        // Add global-error to root layer's filePaths, so that it's always available,
+        // by default it's the built-in global-error.js
+        filePaths.push([GLOBAL_ERROR_FILE_TYPE, globalError])
+
+        // TODO(global-not-found): remove this flag assertion condition
+        //  once global-not-found is stable
+        if (isGlobalNotFoundEnabled) {
+          const resolvedGlobalNotFoundPath = await resolver(
+            `${appDirPrefix}/${GLOBAL_NOT_FOUND_FILE_TYPE}`
+          )
+          if (resolvedGlobalNotFoundPath) {
+            globalNotFound = resolvedGlobalNotFoundPath
+          }
+          // Add global-not-found to root layer's filePaths, so that it's always available,
+          // by default it's the built-in global-not-found.js
+          filePaths.push([GLOBAL_NOT_FOUND_FILE_TYPE, globalNotFound])
+        }
+      }
+
       let definedFilePaths = filePaths.filter(
         ([, filePath]) => filePath !== undefined
       ) as [ValueOf<typeof FILE_TYPES>, string][]
@@ -361,25 +388,6 @@ async function createTreeCodeFromPath(
         }
       }
 
-      if (!globalError) {
-        const resolvedGlobalErrorPath = await resolver(
-          `${appDirPrefix}/${GLOBAL_ERROR_FILE_TYPE}`
-        )
-        if (resolvedGlobalErrorPath) {
-          globalError = resolvedGlobalErrorPath
-        }
-      }
-      // TODO(global-not-found): remove this flag assertion condition
-      //  once global-not-found is stable
-      if (isGlobalNotFoundEnabled && !globalNotFound) {
-        const resolvedGlobalNotFoundPath = await resolver(
-          `${appDirPrefix}/${GLOBAL_NOT_FOUND_FILE_TYPE}`
-        )
-        if (resolvedGlobalNotFoundPath) {
-          globalNotFound = resolvedGlobalNotFoundPath
-        }
-      }
-
       let parallelSegmentKey = Array.isArray(parallelSegment)
         ? parallelSegment[0]
         : parallelSegment
@@ -523,8 +531,8 @@ async function createTreeCodeFromPath(
     treeCode: `${treeCode}.children;`,
     pages: `${JSON.stringify(pages)};`,
     rootLayout,
-    globalError: globalError ?? defaultGlobalErrorPath,
-    globalNotFound: globalNotFound ?? defaultNotFoundPath,
+    globalError,
+    globalNotFound,
   }
 }
 

packages/next/src/server/app-render/app-render.tsx

@@ -97,11 +97,7 @@ import { getRequiredScripts } from './required-scripts'
 import { addPathPrefix } from '../../shared/lib/router/utils/add-path-prefix'
 import { makeGetServerInsertedHTML } from './make-get-server-inserted-html'
 import { walkTreeWithFlightRouterState } from './walk-tree-with-flight-router-state'
-import {
-  createComponentTree,
-  getRootParams,
-  normalizeConventionFilePath,
-} from './create-component-tree'
+import { createComponentTree, getRootParams } from './create-component-tree'
 import { getAssetQueryString } from './get-asset-query-string'
 import {
   getServerModuleMap,
@@ -200,6 +196,7 @@ import {
 } from './module-loading/track-module-loading.external'
 import { isReactLargeShellError } from './react-large-shell-error'
 import type { GlobalErrorComponent } from '../../client/components/builtin/global-error'
+import { normalizeConventionFilePath } from './segment-explorer-path'
 
 export type GetDynamicParamFromSegment = (
   // [slug] / [[slug]] / [...slug]

packages/next/src/server/app-render/create-component-tree.tsx

@@ -26,6 +26,7 @@ import type {
   UseCachePageComponentProps,
 } from '../use-cache/use-cache-wrapper'
 import { DEFAULT_SEGMENT_KEY } from '../../shared/lib/segment'
+import { getConventionPathByType } from './segment-explorer-path'
 
 /**
  * Use the provided loader tree to create the React Component tree.
@@ -1102,53 +1103,3 @@ async function createBoundaryConventionElement({
 
   return wrappedElement
 }
-
-export function normalizeConventionFilePath(
-  projectDir: string,
-  conventionPath: string | undefined
-) {
-  const cwd = process.env.NEXT_RUNTIME === 'edge' ? '' : process.cwd()
-  const nextInternalPrefixRegex =
-    /^(.*[\\/])?next[\\/]dist[\\/]client[\\/]components[\\/]builtin[\\/]/
-
-  let relativePath = (conventionPath || '')
-    // remove turbopack [project] prefix
-    .replace(/^\[project\][\\/]/, '')
-    // remove the project root from the path
-    .replace(projectDir, '')
-    // remove cwd prefix
-    .replace(cwd, '')
-    // remove /(src/)?app/ dir prefix
-    .replace(/^([\\/])*(src[\\/])?app[\\/]/, '')
-
-  // If it's internal file only keep the filename, strip nextjs internal prefix
-  if (nextInternalPrefixRegex.test(relativePath)) {
-    relativePath = relativePath.replace(nextInternalPrefixRegex, '')
-  }
-
-  return relativePath
-}
-
-function getConventionPathByType(
-  tree: LoaderTree,
-  dir: string,
-  conventionType:
-    | 'layout'
-    | 'template'
-    | 'page'
-    | 'not-found'
-    | 'error'
-    | 'loading'
-    | 'forbidden'
-    | 'unauthorized'
-    | 'defaultPage'
-) {
-  const modules = tree[2]
-  const conventionPath = modules[conventionType]
-    ? modules[conventionType][1]
-    : undefined
-  if (conventionPath) {
-    return normalizeConventionFilePath(dir, conventionPath)
-  }
-  return undefined
-}

packages/next/src/server/app-render/segment-explorer-path.ts

@@ -0,0 +1,51 @@
+import type { LoaderTree } from '../lib/app-dir-module'
+
+export function normalizeConventionFilePath(
+  projectDir: string,
+  conventionPath: string | undefined
+) {
+  const cwd = process.env.NEXT_RUNTIME === 'edge' ? '' : process.cwd()
+  const nextInternalPrefixRegex =
+    /^(.*[\\/])?next[\\/]dist[\\/]client[\\/]components[\\/]builtin[\\/]/
+
+  let relativePath = (conventionPath || '')
+    // remove turbopack [project] prefix
+    .replace(/^\[project\][\\/]/, '')
+    // remove the project root from the path
+    .replace(projectDir, '')
+    // remove cwd prefix
+    .replace(cwd, '')
+    // remove /(src/)?app/ dir prefix
+    .replace(/^([\\/])*(src[\\/])?app[\\/]/, '')
+
+  // If it's internal file only keep the filename, strip nextjs internal prefix
+  if (nextInternalPrefixRegex.test(relativePath)) {
+    relativePath = relativePath.replace(nextInternalPrefixRegex, '')
+  }
+
+  return relativePath
+}
+
+export function getConventionPathByType(
+  tree: LoaderTree,
+  dir: string,
+  conventionType:
+    | 'layout'
+    | 'template'
+    | 'page'
+    | 'not-found'
+    | 'error'
+    | 'loading'
+    | 'forbidden'
+    | 'unauthorized'
+    | 'defaultPage'
+) {
+  const modules = tree[2]
+  const conventionPath = modules[conventionType]
+    ? modules[conventionType][1]
+    : undefined
+  if (conventionPath) {
+    return normalizeConventionFilePath(dir, conventionPath)
+  }
+  return undefined
+}

test/development/app-dir/segment-explorer/app/global-error.tsx renamed to test/development/app-dir/segment-explorer-globals/app/global-error.tsx

@@ -3,11 +3,9 @@
 export default function GlobalError() {
   return (
     <html>
-      <head>
-        <title>Global Error</title>
-      </head>
       <body>
         <h1>Global Error</h1>
+        <p>This is a global error</p>
       </body>
     </html>
   )

test/development/app-dir/segment-explorer-globals/app/global-not-found.tsx

@@ -0,0 +1,10 @@
+export default function GlobalNotFound() {
+  return (
+    <html>
+      <body>
+        <h1>404</h1>
+        <p>Not Found Page</p>
+      </body>
+    </html>
+  )
+}

test/development/app-dir/segment-explorer-globals/app/layout.tsx

@@ -0,0 +1,16 @@
+export const metadata = {
+  title: 'Next.js',
+  description: 'Generated by Next.js',
+}
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  )
+}

test/development/app-dir/segment-explorer-globals/app/page.tsx

@@ -0,0 +1,26 @@
+import Link from 'next/link'
+
+const hrefs = [
+  '/parallel-routes',
+  '/blog/~/grid',
+  '/soft-navigation/a',
+  '/file-segments',
+  '/parallel-default',
+  '/parallel-default/subroute',
+]
+
+export default function Page() {
+  return (
+    <div>
+      <h1>Segment Explorer</h1>
+      <p>Examples</p>
+      <div>
+        {hrefs.map((href) => (
+          <div key={href}>
+            <Link href={href}>{href}</Link>
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}

test/development/app-dir/segment-explorer-globals/app/runtime-error/boundary/error.css

@@ -0,0 +1,5 @@
+.error-title {
+  color: red;
+  font-size: 24px;
+  font-weight: bold;
+}

test/development/app-dir/segment-explorer-globals/app/runtime-error/boundary/error.tsx

@@ -0,0 +1,7 @@
+'use client'
+
+import './error.css'
+
+export default function CustomError() {
+  return <h2 className="error-title">Custom Error</h2>
+}

test/development/app-dir/segment-explorer-globals/app/runtime-error/boundary/page.tsx

@@ -0,0 +1,8 @@
+'use client'
+
+export default function Page() {
+  if (typeof window !== 'undefined') {
+    throw new Error('Error on client')
+  }
+  return <p>page</p>
+}

test/development/app-dir/segment-explorer-globals/app/runtime-error/page.tsx

@@ -0,0 +1,8 @@
+'use client'
+
+export default function Page() {
+  if (typeof window !== 'undefined') {
+    throw new Error('Error on client')
+  }
+  return <p>page</p>
+}

test/development/app-dir/segment-explorer-globals/next.config.js

@@ -0,0 +1,12 @@
+/**
+ * @type {import('next').NextConfig}
+ */
+const nextConfig = {
+  experimental: {
+    devtoolSegmentExplorer: true,
+    authInterrupts: true,
+    globalNotFound: true,
+  },
+}
+
+module.exports = nextConfig

test/development/app-dir/segment-explorer-globals/segment-explorer-globals.test.ts

@@ -0,0 +1,41 @@
+import { nextTestSetup } from 'e2e-utils'
+import { openDevToolsIndicatorPopover } from 'next-test-utils'
+import { Playwright } from 'next-webdriver'
+
+async function getSegmentExplorerContent(browser: Playwright) {
+  // open the devtool button
+  await openDevToolsIndicatorPopover(browser)
+
+  // open the segment explorer
+  await browser.elementByCss('[data-segment-explorer]').click()
+
+  //  wait for the segment explorer to be visible
+  await browser.waitForElementByCss('[data-nextjs-devtool-segment-explorer]')
+
+  const content = await browser.elementByCss(
+    '[data-nextjs-devtool-segment-explorer]'
+  )
+  return content.text()
+}
+
+describe('segment-explorer - globals', () => {
+  const { next } = nextTestSetup({
+    files: __dirname,
+  })
+
+  it('should show global-error segment', async () => {
+    const browser = await next.browser('/runtime-error')
+    expect(await getSegmentExplorerContent(browser)).toMatchInlineSnapshot(`
+     "app/
+     global-error.tsx"
+    `)
+  })
+
+  it('should display parallel routes default page when present', async () => {
+    const browser = await next.browser('/404-not-found')
+    expect(await getSegmentExplorerContent(browser)).toMatchInlineSnapshot(`
+     "app/
+     global-not-found.tsx"
+    `)
+  })
+})