feat: generate types for next/root-params during build and dev

Collects root layout dynamic segments during type generation and
emits a typed `declare module 'next/root-params'` declaration to
.next/types/root-params.d.ts. The declaration is included via the
routes.d.ts entry file when experimental.rootParams (or cacheComponents)
is enabled.

- simple [param] → Promise<string>
- [...param] (catch-all) → Promise<string[]>
- [[...param]] (optional catch-all) → Promise<string[] | undefined>
- multiple root layouts with the same param name use the most permissive type

Also adds a typecheck test that builds the existing root-params fixtures
and verifies the generated types match expected return types.

Author: bgub

packages/next/src/build/index.ts

@@ -219,6 +219,7 @@ import {
   writeValidatorFile,
   writeRouteTypesEntryFile,
   writeCacheLifeTypesFile,
+  writeRootParamsTypesFile,
 } from '../server/lib/router-utils/route-types-utils'
 import { Lockfile } from './lockfile'
 import {
@@ -1402,10 +1403,15 @@ export default async function build(
             'types',
             'routes.d.ts'
           )
+          const isRootParamsEnabled = Boolean(
+            config.experimental.rootParams ?? config.cacheComponents
+          )
+
           const actualTypesDir = path.join(distDir, 'types')
           await writeRouteTypesEntryFile(entryFilePath, actualTypesDir, {
             strictRouteTypes: Boolean(config.experimental.strictRouteTypes),
             typedRoutes: Boolean(config.typedRoutes),
+            rootParams: isRootParamsEnabled,
           })
 
           // Generate cache-life types if custom profiles are configured
@@ -1421,6 +1427,19 @@ export default async function build(
               cacheLifeTypesFilePath
             )
           }
+
+          // Generate root params types if experimental.rootParams (or cacheComponents) is enabled
+          if (isRootParamsEnabled) {
+            const rootParamsTypesFilePath = path.join(
+              distDir,
+              'types',
+              'root-params.d.ts'
+            )
+            writeRootParamsTypesFile(
+              routeTypesManifest,
+              rootParamsTypesFilePath
+            )
+          }
         })
 
       // Turbopack already handles conflicting app and page routes.

packages/next/src/server/lib/router-utils/root-params-type-utils.ts

@@ -0,0 +1,56 @@
+import fs from 'fs'
+import path from 'path'
+
+export type RootParamKind = 'dynamic' | 'catchall' | 'optional-catchall'
+
+/**
+ * Generates TypeScript type definitions for the next/root-params virtual module.
+ * Creates typed getter functions for each root param found in the app's root layouts.
+ */
+export function generateRootParamsTypes(
+  rootParams: Map<string, RootParamKind>
+): string {
+  const entries = Array.from(rootParams.entries()).sort(([a], [b]) =>
+    a.localeCompare(b)
+  )
+
+  const functions = entries.map(([name, kind]) => {
+    const returnType =
+      kind === 'dynamic'
+        ? 'Promise<string>'
+        : kind === 'catchall'
+          ? 'Promise<string[]>'
+          : 'Promise<string[] | undefined>'
+    return `  export function ${name}(): ${returnType}`
+  })
+
+  return `// Type definitions for Next.js root params
+
+declare module 'next/root-params' {
+${functions.join('\n')}
+}
+`
+}
+
+/**
+ * Writes root params type definitions to a file if rootParams exist.
+ * This is used by both the CLI (next type-gen) and dev server to generate
+ * root-params.d.ts in the types directory.
+ */
+export function writeRootParamsTypes(
+  rootParams: Map<string, RootParamKind> | undefined,
+  filePath: string
+) {
+  if (!rootParams || rootParams.size === 0) {
+    return
+  }
+
+  const dirname = path.dirname(filePath)
+
+  if (!fs.existsSync(dirname)) {
+    fs.mkdirSync(dirname, { recursive: true })
+  }
+
+  const content = generateRootParamsTypes(rootParams)
+  fs.writeFileSync(filePath, content)
+}

packages/next/src/server/lib/router-utils/route-types-utils.ts

@@ -14,6 +14,11 @@ import {
   generateRouteTypesFileStrict,
 } from './typegen'
 import { writeCacheLifeTypes } from './cache-life-type-utils'
+import {
+  writeRootParamsTypes,
+  type RootParamKind,
+} from './root-params-type-utils'
+import { getSegmentParam } from '../../../shared/lib/router/utils/get-segment-param'
 import { tryToParsePath } from '../../../lib/try-to-parse-path'
 import {
   extractInterceptionRouteInformation,
@@ -52,6 +57,8 @@ export interface RouteTypesManifest {
   filePathToRoute: Map<string, string>
   /** Cache life configuration for generating cache-life.d.ts */
   cacheLifeConfig?: { [profile: string]: CacheLife }
+  /** Root params collected from root layouts for generating root-params.d.ts */
+  rootParams?: Map<string, RootParamKind>
 }
 
 // Convert a custom-route source string (`/blog/:slug`, `/docs/:path*`, ...)
@@ -148,6 +155,68 @@ function resolveInterceptingRoute(route: string): string {
   }
 }
 
+/**
+ * Identifies root layouts and collects their dynamic segments as root params.
+ * A root layout is the shallowest layout in each branch of the app directory.
+ */
+function collectRootParamsFromLayouts(
+  layoutRoutes: RouteInfo[]
+): Map<string, RootParamKind> {
+  const rootParams = new Map<string, RootParamKind>()
+
+  // Sort by depth (fewer path segments = shallower = more likely to be root)
+  const sorted = [...layoutRoutes].sort(
+    (a, b) => a.route.split('/').length - b.route.split('/').length
+  )
+
+  const rootLayoutRoutes: string[] = []
+
+  for (const { route } of sorted) {
+    // Skip internal routes
+    if (
+      route === UNDERSCORE_GLOBAL_ERROR_ROUTE ||
+      route === UNDERSCORE_NOT_FOUND_ROUTE
+    ) {
+      continue
+    }
+
+    // A layout is a root layout if no already-found root layout is an ancestor of it
+    const hasAncestorRootLayout = rootLayoutRoutes.some((rootRoute) =>
+      rootRoute === '/' ? route !== '/' : route.startsWith(rootRoute + '/')
+    )
+
+    if (hasAncestorRootLayout) continue
+
+    rootLayoutRoutes.push(route)
+
+    // Extract dynamic segments from this root layout's route
+    for (const segment of route.split('/')) {
+      const param = getSegmentParam(segment)
+      if (param === null) continue
+
+      const kind: RootParamKind =
+        param.paramType === 'optional-catchall'
+          ? 'optional-catchall'
+          : param.paramType === 'catchall'
+            ? 'catchall'
+            : 'dynamic'
+
+      // If the same param name appears in multiple root layouts with different
+      // kinds, keep the most permissive type.
+      const existing = rootParams.get(param.paramName)
+      if (
+        !existing ||
+        kind === 'optional-catchall' ||
+        (kind === 'catchall' && existing === 'dynamic')
+      ) {
+        rootParams.set(param.paramName, kind)
+      }
+    }
+  }
+
+  return rootParams
+}
+
 /**
  * Creates a route types manifest from processed route data
  * (used for both build and dev)
@@ -354,6 +423,8 @@ export async function createRouteTypesManifest({
     }
   }
 
+  manifest.rootParams = collectRootParamsFromLayouts(layoutRoutes)
+
   return manifest
 }
 
@@ -417,6 +488,7 @@ export async function writeRouteTypesEntryFile(
   options: {
     strictRouteTypes: boolean
     typedRoutes: boolean
+    rootParams?: boolean
   }
 ) {
   const entryDir = path.dirname(entryFilePath)
@@ -436,6 +508,10 @@ export async function writeRouteTypesEntryFile(
     `export type * from "${prefix}route-types.d.ts";`,
   ]
 
+  if (options.rootParams) {
+    lines.push(`import "${prefix}root-params.d.ts";`)
+  }
+
   if (options.strictRouteTypes) {
     lines.push(`import "${prefix}cache-life.d.ts";`)
     lines.push(`import "${prefix}validator.ts";`)
@@ -456,3 +532,10 @@ export async function writeCacheLifeTypesFile(
 ) {
   writeCacheLifeTypes(manifest.cacheLifeConfig, filePath)
 }
+
+export function writeRootParamsTypesFile(
+  manifest: RouteTypesManifest,
+  filePath: string
+) {
+  writeRootParamsTypes(manifest.rootParams, filePath)
+}

packages/next/src/server/lib/router-utils/setup-dev-bundler.ts

@@ -88,6 +88,7 @@ import {
   writeRouteTypesManifest,
   writeValidatorFile,
   writeRouteTypesEntryFile,
+  writeRootParamsTypesFile,
 } from './route-types-utils'
 import { writeCacheLifeTypes } from './cache-life-type-utils'
 import {
@@ -1204,6 +1205,18 @@ async function startWatcher(
           const cacheLifeFilePath = path.join(distTypesDir, 'cache-life.d.ts')
           writeCacheLifeTypes(opts.nextConfig.cacheLife, cacheLifeFilePath)
 
+          // Generate root params types if experimental.rootParams (or cacheComponents) is enabled
+          const isRootParamsEnabled = Boolean(
+            nextConfig.experimental.rootParams ?? nextConfig.cacheComponents
+          )
+          if (isRootParamsEnabled) {
+            const rootParamsFilePath = path.join(
+              distTypesDir,
+              'root-params.d.ts'
+            )
+            writeRootParamsTypesFile(routeTypesManifest, rootParamsFilePath)
+          }
+
           // Write the entry file at {distDirRoot}/types/routes.d.ts
           // This ensures next-env.d.ts has a consistent import path
           const entryFilePath = path.join(
@@ -1215,6 +1228,7 @@ async function startWatcher(
           await writeRouteTypesEntryFile(entryFilePath, distTypesDir, {
             strictRouteTypes: Boolean(nextConfig.experimental.strictRouteTypes),
             typedRoutes: Boolean(nextConfig.typedRoutes),
+            rootParams: isRootParamsEnabled,
           })
         }
 

test/e2e/app-dir/app-root-params-getters/fixtures/simple/type-tests.ts

@@ -0,0 +1,13 @@
+// This file is type-checked by typecheck.test.ts after building the fixture.
+// It verifies that the generated next/root-params types are correct.
+import { lang, locale, path } from 'next/root-params'
+
+// lang and locale are simple dynamic segments → Promise<string>
+const langResult: Promise<string> = lang()
+const localeResult: Promise<string> = locale()
+
+// path appears in both catch-all and optional-catch-all layouts →
+// most permissive type wins: Promise<string[] | undefined>
+const pathResult: Promise<string[] | undefined> = path()
+
+export { langResult, localeResult, pathResult }

test/e2e/app-dir/app-root-params-getters/typecheck.test.ts

@@ -0,0 +1,81 @@
+/* eslint-env jest */
+import path from 'path'
+import fs from 'fs-extra'
+import { nextBuild } from 'next-test-utils'
+import execa from 'execa'
+
+const simpleFixtureDir = path.join(__dirname, 'fixtures', 'simple')
+const multipleRootsFixtureDir = path.join(
+  __dirname,
+  'fixtures',
+  'multiple-roots'
+)
+
+// Turbopack doesn't use this type generation path (handled in Rust)
+describe('root params type generation', () => {
+  describe('simple fixture', () => {
+    beforeAll(async () => {
+      await nextBuild(simpleFixtureDir, [], { stderr: true })
+    })
+
+    it('should generate root-params.d.ts with correct types', async () => {
+      const dts = (
+        await fs.readFile(
+          path.join(simpleFixtureDir, '.next', 'types', 'root-params.d.ts')
+        )
+      ).toString()
+
+      // lang and locale are simple dynamic segments → Promise<string>
+      expect(dts).toContain(`export function lang(): Promise<string>`)
+      expect(dts).toContain(`export function locale(): Promise<string>`)
+
+      // path appears in catch-all and optional-catch-all → most permissive wins
+      expect(dts).toContain(
+        `export function path(): Promise<string[] | undefined>`
+      )
+    })
+
+    it('should include root-params.d.ts import in entry file', async () => {
+      const entryFile = (
+        await fs.readFile(
+          path.join(simpleFixtureDir, '.next', 'types', 'routes.d.ts')
+        )
+      ).toString()
+
+      expect(entryFile).toContain(`import "./root-params.d.ts"`)
+    })
+
+    it('should type-check correctly', async () => {
+      const result = await execa('tsc', ['--noEmit'], {
+        cwd: simpleFixtureDir,
+        reject: false,
+      })
+      expect(result.stderr).not.toContain('error TS')
+      expect(result.stdout).not.toContain('error TS')
+    })
+  })
+
+  describe('multiple-roots fixture', () => {
+    beforeAll(async () => {
+      await nextBuild(multipleRootsFixtureDir, [], { stderr: true })
+    })
+
+    it('should generate root-params.d.ts with correct types', async () => {
+      const dts = (
+        await fs.readFile(
+          path.join(
+            multipleRootsFixtureDir,
+            '.next',
+            'types',
+            'root-params.d.ts'
+          )
+        )
+      ).toString()
+
+      // Only the dashboard subtree has a dynamic segment
+      expect(dts).toContain(`export function id(): Promise<string>`)
+      // landing layout has no params
+      expect(dts).not.toContain('lang')
+    })
+  })
+})