feat: type guard file

Author: bgub

packages/next/src/lib/typescript/writeAppTypeDeclarations.ts

@@ -59,6 +59,7 @@ export async function writeAppTypeDeclarations({
 
   if (hasNewTypedRoutes) {
     directives.push('/// <reference path="./.next/types/routes.ts" />')
+    directives.push('/// <reference path="./.next/types/validator.ts" />')
   }
 
   // Push the notice in.

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

@@ -83,7 +83,7 @@ import {
   TurbopackInternalError,
 } from '../../../shared/lib/turbopack/utils'
 import { getDefineEnv } from '../../../build/define-env'
-import { generateRouteTypesFile } from './typegen'
+import { generateRouteTypesFile, generateValidatorFile } from './typegen'
 
 export type SetupOpts = {
   renderServer: LazyRenderServerInstance
@@ -160,6 +160,11 @@ export interface RouteTypesManifest {
     string,
     { path: string } | { slots: string[]; path: string }
   >
+
+  // For validator.ts - all file paths
+  appPaths: string[]
+  pagePaths: string[]
+  layoutPaths: string[]
 }
 
 function createRouteTypesManifest({
@@ -168,12 +173,18 @@ function createRouteTypesManifest({
   appPageFilePaths,
   appLayoutFilePaths,
   layoutSlots,
+  allAppPagePaths,
+  allPagesPagePaths,
+  allAppLayoutPaths,
 }: {
   dir: string
   pagesPageFilePaths: Map<string, string>
   appPageFilePaths: Map<string, string>
   appLayoutFilePaths: Map<string, string>
   layoutSlots: Map<string, Set<string>>
+  allAppPagePaths: Set<string>
+  allPagesPagePaths: Set<string>
+  allAppLayoutPaths: Set<string>
 }): RouteTypesManifest {
   const appRoutes: Record<string, { path: string }> = {}
   const pageRoutes: Record<string, { path: string }> = {}
@@ -212,10 +223,17 @@ function createRouteTypesManifest({
     }
   }
 
+  const appPaths = Array.from(allAppPagePaths).sort()
+  const pagePaths = Array.from(allPagesPagePaths).sort()
+  const layoutPaths = Array.from(allAppLayoutPaths).sort()
+
   return {
     appRoutes,
     pageRoutes,
     layoutRoutes,
+    appPaths,
+    pagePaths,
+    layoutPaths,
   }
 }
 
@@ -310,12 +328,22 @@ async function startWatcher(
       appPageFilePaths: new Map(),
       appLayoutFilePaths: new Map(),
       layoutSlots: new Map(),
+      allAppPagePaths: new Set(),
+      allPagesPagePaths: new Set(),
+      allAppLayoutPaths: new Set(),
     })
 
     await fs.promises.writeFile(
       routeTypesFilePath,
       generateRouteTypesFile(routeTypesManifest)
     )
+
+    // Generate validator file
+    const validatorFilePath = path.join(distDir, 'types', 'validator.ts')
+    await fs.promises.writeFile(
+      validatorFilePath,
+      generateValidatorFile(routeTypesManifest)
+    )
   }
 
   const prerenderManifestPath = path.join(distDir, PRERENDER_MANIFEST)
@@ -420,6 +448,11 @@ async function startWatcher(
       const appLayoutFilePaths = new Map<string, string>()
       const layoutSlots = new Map<string, Set<string>>()
 
+      // Separate collections for ALL file paths (for validator.ts)
+      const allAppPagePaths = new Set<string>()
+      const allPagesPagePaths = new Set<string>()
+      const allAppLayoutPaths = new Set<string>()
+
       let envChange = false
       let tsconfigChange = false
       let conflictingPageChange = 0
@@ -550,6 +583,19 @@ async function startWatcher(
         // Collect all current filenames for the TS plugin to use
         devPageFiles.add(fileName)
 
+        const relativePath = path.relative(dir, fileName)
+
+        // Collect ALL file paths for validator.ts (before any filtering)
+        if (opts.nextConfig.experimental.newTypedRoutes) {
+          if (isAppPath && layoutFileRegex.test(fileName)) {
+            allAppLayoutPaths.add(relativePath)
+          } else if (isAppPath && validFileMatcher.isAppRouterPage(fileName)) {
+            allAppPagePaths.add(relativePath)
+          } else if (!isAppPath && validFileMatcher.isPageFile(fileName)) {
+            allPagesPagePaths.add(relativePath)
+          }
+        }
+
         let pageName = absolutePathToPage(fileName, {
           dir: isAppPath ? appDir! : pagesDir!,
           extensions: nextConfig.pageExtensions,
@@ -655,6 +701,7 @@ async function startWatcher(
             continue
           }
         } else {
+          // pages directory
           if (useFileSystemPublicRoutes) {
             pageFiles.add(pageName)
             // always add to nextDataRoutes for now but in future only add
@@ -1067,12 +1114,22 @@ async function startWatcher(
             appPageFilePaths,
             appLayoutFilePaths,
             layoutSlots,
+            allAppPagePaths,
+            allPagesPagePaths,
+            allAppLayoutPaths,
           })
 
           await fs.promises.writeFile(
             routeTypesFilePath,
             generateRouteTypesFile(routeTypesManifest)
           )
+
+          // Generate validator file
+          const validatorFilePath = path.join(distDir, 'types', 'validator.ts')
+          await fs.promises.writeFile(
+            validatorFilePath,
+            generateValidatorFile(routeTypesManifest)
+          )
         }
 
         if (!resolved) {

packages/next/src/server/lib/router-utils/typegen.ts

@@ -23,6 +23,100 @@ function deterministicSerialize(obj: object): string {
   )
 }
 
+export function generateValidatorFile(
+  routesManifest: RouteTypesManifest
+): string {
+  const { appPaths, pagePaths, layoutPaths } = routesManifest
+  const basePrefix = '../..'
+
+  const generateImports = (paths: string[]) =>
+    paths
+      .sort()
+      .map((filePath) => {
+        const importPath = `${basePrefix}/${filePath.replace(/\.(tsx?|jsx?)$/, '')}`
+        return `  ${JSON.stringify(filePath)}: typeof import(${JSON.stringify(importPath)})`
+      })
+      .join(',\n')
+
+  const appPageImports = generateImports(appPaths)
+  const pagesPageImports = generateImports(pagePaths)
+  const allPageImports = [appPageImports, pagesPageImports]
+    .filter(Boolean)
+    .join(',\n')
+  const layoutImports = generateImports(layoutPaths)
+
+  const generateValidations = (
+    paths: string[],
+    type: 'PageConfig' | 'LayoutConfig'
+  ) =>
+    paths
+      .sort()
+      .map((filePath) => {
+        const importType = type === 'PageConfig' ? 'Pages' : 'Layouts'
+        return `// Validate ${filePath}
+{
+  const handler = {} as ${importType}[${JSON.stringify(filePath)}]
+  handler satisfies ${type}
+}`
+      })
+      .join('\n\n')
+
+  const pageValidations = generateValidations(
+    [...appPaths, ...pagePaths],
+    'PageConfig'
+  )
+  const layoutValidations = generateValidations(layoutPaths, 'LayoutConfig')
+
+  return `// This file is generated automatically by Next.js
+// Do not edit this file manually
+// This file validates that all pages and layouts export the correct types
+
+type PageConfig = {
+  default: React.ComponentType<any>
+  config?: {}
+  generateStaticParams?: () => Promise<any[]> | any[]
+  generateMetadata?: (props: any, parent: any) => Promise<any> | any
+  generateViewport?: (props: any, parent: any) => Promise<any> | any
+  revalidate?: number | false
+  dynamic?: 'auto' | 'force-dynamic' | 'error' | 'force-static'
+  dynamicParams?: boolean
+  fetchCache?: 'auto' | 'force-no-store' | 'only-no-store' | 'default-no-store' | 'default-cache' | 'only-cache' | 'force-cache'
+  preferredRegion?: 'auto' | 'global' | 'home' | string | string[]
+  runtime?: 'nodejs' | 'experimental-edge' | 'edge'
+  maxDuration?: number
+  experimental_ppr?: boolean
+}
+
+type LayoutConfig = {
+  default: React.ComponentType<{ children: React.ReactNode }>
+  config?: {}
+  generateStaticParams?: () => Promise<any[]> | any[]
+  generateMetadata?: (props: any, parent: any) => Promise<any> | any
+  generateViewport?: (props: any, parent: any) => Promise<any> | any
+  revalidate?: number | false
+  dynamic?: 'auto' | 'force-dynamic' | 'error' | 'force-static'
+  dynamicParams?: boolean
+  fetchCache?: 'auto' | 'force-no-store' | 'only-no-store' | 'default-no-store' | 'default-cache' | 'only-cache' | 'force-cache'
+  preferredRegion?: 'auto' | 'global' | 'home' | string | string[]
+  runtime?: 'nodejs' | 'experimental-edge' | 'edge'
+  maxDuration?: number
+  experimental_ppr?: boolean
+}
+
+type Pages = {
+${allPageImports}
+}
+
+type Layouts = {
+${layoutImports}
+}
+
+${pageValidations}
+
+${layoutValidations}
+`
+}
+
 export function generateRouteTypesFile(
   routesManifest: RouteTypesManifest
 ): string {
@@ -44,10 +138,6 @@ type PageRoutes = AppPageRoutes | PagesPageRoutes
 type LayoutRoutes = keyof (typeof routesManifest)['layoutRoutes']
 type Routes = PageRoutes | LayoutRoutes
 
-// -----------------------------------
-// helpers
-// -----------------------------------
-
 type Merge<T> = { [K in keyof T]: T[K] }
 // extract path params
 type Grab<Path extends string> =
@@ -62,10 +152,6 @@ type Grab<Path extends string> =
 type ParamMap = { [P in Routes]: Grab<P> }
 export type ParamsOf<P extends Routes> = ParamMap[P]
 
-// -----------------------------------
-// layout slots
-// -----------------------------------
-
 type SlotMap = {
   [P in LayoutRoutes]:
     (typeof routesManifest)['layoutRoutes'][P] extends { slots: readonly string[] }
@@ -80,17 +166,9 @@ type LayoutChildrenMap = {
 
 type LayoutChildren<P extends LayoutRoutes> = LayoutChildrenMap[P]
 
-// -----------------------------------
-// exports
-// -----------------------------------
-
 export { routesManifest }
 export type { PageRoutes, LayoutRoutes }
 
-// -----------------------------------
-// global types
-// -----------------------------------
-
 declare global {
   /**
    * Props for Next.js App Router page components

test/e2e/typed-routes-new/app/blog/[slug]/page.tsx

@@ -1,3 +1,6 @@
+// This will throw a type error because it's not one of the allowed values!
+// export const dynamic = 'some-random-string'
+
 export default async function BlogPostPage(props: PageProps<'/blog/[slug]'>) {
   const params = await props.params