[webpack] generate types for next/root-params

lubieowoce · lubieowoce · commit 13bd3038e88f · 2025-07-21T16:29:18.000+02:00
diff --git a/packages/next/errors.json b/packages/next/errors.json
@@ -735,5 +735,6 @@
   "734": "\\`unstable_rootParams\\` must not be used within a client component. Next.js should be preventing it from being included in client components statically, but did not in this case.",
   "735": "Missing workStore in %s",
   "736": "Route %s used %s inside a Route Handler. Support for this API in Route Handlers is planned for a future version of Next.js.",
-  "737": "%s was used inside a Server Action. This is not supported. Functions from 'next/root-params' can only be called in the context of a route."
+  "737": "%s was used inside a Server Action. This is not supported. Functions from 'next/root-params' can only be called in the context of a route.",
+  "738": "Unknown param kind %s"
 }
diff --git a/packages/next/src/build/webpack/loaders/next-root-params-loader.ts b/packages/next/src/build/webpack/loaders/next-root-params-loader.ts
@@ -3,21 +3,23 @@ import * as path from 'node:path'
 import * as fs from 'node:fs/promises'
 import { normalizeAppPath } from '../../../shared/lib/router/utils/app-paths'
 import { ensureLeadingSlash } from '../../../shared/lib/page-path/ensure-leading-slash'
+import type { DynamicParamTypes } from '../../../server/app-render/types'
 import { getSegmentParam } from '../../../server/app-render/get-segment-param'
+import { InvariantError } from '../../../shared/lib/invariant-error'
 
 export type RootParamsLoaderOpts = {
   appDir: string
   pageExtensions: string[]
 }
 
-type CollectedRootParams = Set<string>
+export type CollectedRootParams = Map<string, Set<DynamicParamTypes>>
 
 const rootParamsLoader: webpack.LoaderDefinitionFunction<RootParamsLoaderOpts> =
   async function () {
     const { appDir, pageExtensions } = this.getOptions()
 
     const allRootParams = await collectRootParamsFromFileSystem({
-      appDir,
+      appDir: appDir,
       pageExtensions,
     })
     // invalidate the result whenever a file/directory is added/removed inside the app dir or its subdirectories,
@@ -30,7 +32,7 @@ const rootParamsLoader: webpack.LoaderDefinitionFunction<RootParamsLoaderOpts> =
     }
 
     // Generate a getter for each root param we found.
-    const sortedRootParamNames = Array.from(allRootParams).sort()
+    const sortedRootParamNames = Array.from(allRootParams.keys()).sort()
     const content = [
       `import { getRootParam } from 'next/dist/server/request/root-params';`,
       ...sortedRootParamNames.map((paramName) => {
@@ -43,7 +45,7 @@ const rootParamsLoader: webpack.LoaderDefinitionFunction<RootParamsLoaderOpts> =
 
 export default rootParamsLoader
 
-async function collectRootParamsFromFileSystem(
+export async function collectRootParamsFromFileSystem(
   opts: Parameters<typeof findRootLayouts>[0]
 ) {
   return collectRootParams({
@@ -59,15 +61,22 @@ function collectRootParams({
   rootLayoutFilePaths: string[]
   appDir: string
 }): CollectedRootParams {
-  const allRootParams: CollectedRootParams = new Set()
+  // Collect the param names and kinds from all root layouts.
+  // Note that if multiple root layouts use the same param name, it can have multiple kinds.
+  const allRootParams: CollectedRootParams = new Map()
 
   for (const rootLayoutFilePath of rootLayoutFilePaths) {
     const params = getParamsFromLayoutFilePath({
       appDir,
       layoutFilePath: rootLayoutFilePath,
     })
     for (const param of params) {
-      allRootParams.add(param)
+      const { param: paramName, type: paramKind } = param
+      let paramKinds = allRootParams.get(paramName)
+      if (!paramKinds) {
+        allRootParams.set(paramName, (paramKinds = new Set()))
+      }
+      paramKinds.add(paramKind)
     }
   }
 
@@ -144,23 +153,84 @@ async function findRootLayouts({
   return visit(appDir)
 }
 
+type ParamInfo = { param: string; type: DynamicParamTypes }
+
 function getParamsFromLayoutFilePath({
   appDir,
   layoutFilePath,
 }: {
   appDir: string
   layoutFilePath: string
-}): string[] {
+}): ParamInfo[] {
   const rootLayoutPath = normalizeAppPath(
     ensureLeadingSlash(path.dirname(path.relative(appDir, layoutFilePath)))
   )
   const segments = rootLayoutPath.split('/')
-  const paramNames: string[] = []
+  const params: ParamInfo[] = []
   for (const segment of segments) {
     const param = getSegmentParam(segment)
     if (param !== null) {
-      paramNames.push(param.param)
+      params.push(param)
+    }
+  }
+  return params
+}
+
+//=============================================
+// Type declarations
+//=============================================
+
+export function generateDeclarations(rootParams: CollectedRootParams) {
+  const sortedRootParamNames = Array.from(rootParams.keys()).sort()
+  const declarationLines = sortedRootParamNames
+    .map((paramName) => {
+      // A param can have multiple kinds (in different root layouts).
+      // In that case, we'll need to union the types together together.
+      const paramKinds = Array.from(rootParams.get(paramName)!)
+      const possibleTypesForParam = paramKinds.map((kind) =>
+        getTypescriptTypeFromParamKind(kind)
+      )
+      // A root param getter can be called
+      // - in a route handler (not yet implemented)
+      // - a server action (unsupported)
+      // - in another root layout that doesn't share the same root params.
+      // For this reason, we currently always want `... | undefined` in the type.
+      possibleTypesForParam.push(`undefined`)
+
+      const paramType = unionTsTypes(possibleTypesForParam)
+
+      return [
+        `  /** Allows reading the '${paramName}' root param. */`,
+        `  export function ${paramName}(): Promise<${paramType}>`,
+      ].join('\n')
+    })
+    .join('\n\n')
+
+  return `declare module 'next/root-params' {\n${declarationLines}\n}\n`
+}
+
+function getTypescriptTypeFromParamKind(kind: DynamicParamTypes): string {
+  switch (kind) {
+    case 'catchall':
+    case 'catchall-intercepted': {
+      return `string[]`
+    }
+    case 'optional-catchall': {
+      return `string[] | undefined`
+    }
+    case 'dynamic':
+    case 'dynamic-intercepted': {
+      return `string`
+    }
+    default: {
+      kind satisfies never
+      throw new InvariantError(`Unknown param kind ${kind}`)
     }
   }
-  return paramNames
+}
+
+function unionTsTypes(types: string[]) {
+  if (types.length === 0) return 'never'
+  if (types.length === 1) return types[0]
+  return types.map((type) => `(${type})`).join(' | ')
 }
diff --git a/packages/next/src/build/webpack/plugins/next-types-plugin/index.ts b/packages/next/src/build/webpack/plugins/next-types-plugin/index.ts
@@ -18,6 +18,10 @@ import type { PageExtensions } from '../../../page-extensions-type'
 import { devPageFiles } from './shared'
 import { getProxiedPluginState } from '../../../build-context'
 import type { CacheLife } from '../../../../server/use-cache/cache-life'
+import {
+  collectRootParamsFromFileSystem,
+  generateDeclarations,
+} from '../../loaders/next-root-params-loader'
 
 const PLUGIN_NAME = 'NextTypesPlugin'
 
@@ -237,6 +241,7 @@ async function collectNamedSlots(layoutPath: string) {
 // possible to provide the same experience for dynamic routes.
 
 const pluginState = getProxiedPluginState({
+  // used for unstable_rootParams()
   collectedRootParams: {} as Record<string, string[]>,
   routeTypes: {
     edge: {
@@ -1038,6 +1043,14 @@ export class NextTypesPlugin {
             pluginState.routeTypes.node.static = []
           }
 
+          // We can't rely on webpack's module graph, because in dev we do on-demand compilation,
+          // so we'd miss the layouts that haven't been compiled yet
+          const rootParamsPromise = collectRootParamsFromFileSystem({
+            appDir: this.appDir,
+            pageExtensions: this.pageExtensions,
+            trackDirectory: undefined,
+          })
+
           compilation.chunkGroups.forEach((chunkGroup) => {
             chunkGroup.chunks.forEach((chunk) => {
               if (!chunk.name) return
@@ -1076,6 +1089,7 @@ export class NextTypesPlugin {
 
           await Promise.all(promises)
 
+          // unstable_rootParams()
           const rootParams = getRootParamsFromLayouts(
             pluginState.collectedRootParams
           )
@@ -1095,6 +1109,17 @@ export class NextTypesPlugin {
             )
           }
 
+          // next/root-params
+          const collectedRootParams = await rootParamsPromise
+          const rootParamsTypesPath = path.join(
+            assetDirRelative,
+            'types/root-params.d.ts'
+          )
+          compilation.emitAsset(
+            rootParamsTypesPath,
+            new sources.RawSource(generateDeclarations(collectedRootParams))
+          )
+
           // Support `"moduleResolution": "Node16" | "NodeNext"` with `"type": "module"`
 
           const packageJsonAssetPath = path.join(

Original file line number	Diff line number	Diff line change
`@@ -735,5 +735,6 @@`
`735`	`735`	"734": "\\`unstable_rootParams\\` must not be used within a client component. Next.js should be preventing it from being included in client components statically, but did not in this case.",
`736`	`736`	`"735": "Missing workStore in %s",`
`737`	`737`	`"736": "Route %s used %s inside a Route Handler. Support for this API in Route Handlers is planned for a future version of Next.js.",`
`738`		`- "737": "%s was used inside a Server Action. This is not supported. Functions from 'next/root-params' can only be called in the context of a route."`
	`738`	`+ "737": "%s was used inside a Server Action. This is not supported. Functions from 'next/root-params' can only be called in the context of a route.",`
	`739`	`+ "738": "Unknown param kind %s"`
`739`	`740`	`}`