feat: generate type guard file

Author: bgub

.vscode/settings.json

@@ -118,5 +118,8 @@
     "${workspaceRoot}/.git-blame-ignore-revs"
   ],
   "astGrep.serverPath": "node_modules/@ast-grep/cli/ast-grep",
-  "rust-analyzer.imports.prefix": "crate"
+  "rust-analyzer.imports.prefix": "crate",
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  }
 }

packages/next/src/build/entries.ts

@@ -76,27 +76,25 @@ import type { MappedPages } from './build-context'
 import { PAGE_TYPES } from '../lib/page-types'
 import { isAppPageRoute } from '../lib/is-app-page-route'
 import { recursiveReadDir } from '../lib/recursive-readdir'
-import { createValidFileMatcher } from '../server/lib/find-page-file'
+import type { createValidFileMatcher } from '../server/lib/find-page-file'
 import { isReservedPage } from './utils'
 import { isParallelRouteSegment } from '../shared/lib/segment'
 import { ensureLeadingSlash } from '../shared/lib/page-path/ensure-leading-slash'
 
 /**
  * Collect app pages and layouts from the app directory
  * @param appDir - The app directory path
- * @param pageExtensions - The configured page extensions
+ * @param validFileMatcher - File matcher object
  * @param options - Optional configuration
  * @returns Object containing appPaths and layoutPaths arrays
  */
 export async function collectAppFiles(
   appDir: string,
-  pageExtensions: PageExtensions
+  validFileMatcher: ReturnType<typeof createValidFileMatcher>
 ): Promise<{
   appPaths: string[]
   layoutPaths: string[]
 }> {
-  const validFileMatcher = createValidFileMatcher(pageExtensions, appDir)
-
   // Collect both app pages and layouts in a single directory traversal
   const allAppFiles = await recursiveReadDir(appDir, {
     pathnameFilter: (absolutePath) =>
@@ -127,14 +125,10 @@ export async function collectAppFiles(
  */
 export async function collectPagesFiles(
   pagesDir: string,
-  pageExtensions: PageExtensions
+  validFileMatcher: ReturnType<typeof createValidFileMatcher>
 ): Promise<string[]> {
   return recursiveReadDir(pagesDir, {
-    pathnameFilter: (absolutePath) => {
-      const relativePath = absolutePath.replace(pagesDir + '/', '')
-      return pageExtensions.some((ext) => relativePath.endsWith(`.${ext}`))
-    },
-    ignorePartFilter: (part) => part.startsWith('_'),
+    pathnameFilter: validFileMatcher.isPageFile,
   })
 }
 
@@ -251,22 +245,31 @@ export function extractSlotsFromAppRoutes(mappedAppPages: {
  */
 export function processAppRoutes(
   mappedAppPages: { [page: string]: string },
-  baseDir: string
-): RouteInfo[] {
+  validFileMatcher: ReturnType<typeof createValidFileMatcher>
+): {
+  appRoutes: RouteInfo[]
+  appRouteHandlers: RouteInfo[]
+} {
   const appRoutes: RouteInfo[] = []
+  const appRouteHandlers: RouteInfo[] = []
 
   for (const [route, filePath] of Object.entries(mappedAppPages)) {
     if (route === '/_not-found/page') continue
 
-    const relativeFilePath = createRelativeFilePath(baseDir, filePath, 'app')
-
-    appRoutes.push({
-      route: normalizeAppPath(normalizePathSep(route)),
-      filePath: relativeFilePath,
-    })
+    if (validFileMatcher.isAppRouterRoute(filePath)) {
+      appRouteHandlers.push({
+        route: normalizeAppPath(normalizePathSep(route)),
+        filePath: filePath.replace(/^private-next-app-dir\//, 'app/'),
+      })
+    } else {
+      appRoutes.push({
+        route: normalizeAppPath(normalizePathSep(route)),
+        filePath: filePath.replace(/^private-next-app-dir\//, 'app/'),
+      })
+    }
   }
 
-  return appRoutes
+  return { appRoutes, appRouteHandlers }
 }
 
 /**

packages/next/src/build/index.ts

@@ -117,6 +117,7 @@ import {
   extractSlotsFromAppRoutes,
   type RouteInfo,
   type SlotInfo,
+  collectPagesFiles,
 } from './entries'
 import { PAGE_TYPES } from '../lib/page-types'
 import { generateBuildId } from './generate-build-id'
@@ -145,7 +146,6 @@ import isError from '../lib/is-error'
 import type { NextError } from '../lib/is-error'
 import { isEdgeRuntime } from '../lib/is-edge-runtime'
 import { recursiveCopy } from '../lib/recursive-copy'
-import { recursiveReadDir } from '../lib/recursive-readdir'
 import { lockfilePatchPromise, teardownTraceSubscriber } from './swc'
 import { getNamedRouteRegex } from '../shared/lib/router/utils/route-regex'
 import { getFilesInDir } from '../lib/get-files-in-dir'
@@ -218,9 +218,11 @@ import {
   sortPages,
   sortSortableRouteObjects,
 } from '../shared/lib/router/utils/sortable-routes'
+import { mkdir } from 'fs/promises'
 import {
   createRouteTypesManifest,
   writeRouteTypesManifest,
+  writeValidatorFile,
 } from '../server/lib/router-utils/route-types-utils'
 
 type Fallback = null | boolean | string
@@ -1153,11 +1155,9 @@ export default async function build(
       let pagesPaths = Boolean(process.env.NEXT_PRIVATE_PAGE_PATHS)
         ? providedPagePaths
         : !appDirOnly && pagesDir
-          ? await nextBuildSpan.traceChild('collect-pages').traceAsyncFn(() =>
-              recursiveReadDir(pagesDir, {
-                pathnameFilter: validFileMatcher.isPageFile,
-              })
-            )
+          ? await nextBuildSpan
+              .traceChild('collect-pages')
+              .traceAsyncFn(() => collectPagesFiles(pagesDir, validFileMatcher))
           : []
 
       const middlewareDetectionRegExp = new RegExp(
@@ -1223,13 +1223,14 @@ export default async function build(
         let layoutPaths: string[]
 
         if (Boolean(process.env.NEXT_PRIVATE_APP_PATHS)) {
+          // used for testing?
           appPaths = providedAppPaths
           layoutPaths = []
         } else {
           // Collect both app pages and layouts in a single directory traversal
           const result = await nextBuildSpan
             .traceChild('collect-app-files')
-            .traceAsyncFn(() => collectAppFiles(appDir, config.pageExtensions))
+            .traceAsyncFn(() => collectAppFiles(appDir, validFileMatcher))
 
           appPaths = result.appPaths
           layoutPaths = result.layoutPaths
@@ -1313,25 +1314,25 @@ export default async function build(
         .traceChild('generate-route-types')
         .traceAsyncFn(async () => {
           const routeTypesFilePath = path.join(distDir, 'types', 'routes.d.ts')
-          await fs.mkdir(path.dirname(routeTypesFilePath), { recursive: true })
+          const validatorFilePath = path.join(distDir, 'types', 'validator.ts')
+          await mkdir(path.dirname(routeTypesFilePath), { recursive: true })
 
-          let pageRoutes: RouteInfo[] = []
           let appRoutes: RouteInfo[] = []
+          let appRouteHandlers: RouteInfo[] = []
           let layoutRoutes: RouteInfo[] = []
           let slots: SlotInfo[] = []
 
-          // Build pages routes
-          const processedPages = processPageRoutes(mappedPages, dir)
-          // We combine both page routes and API routes
-          pageRoutes = [
-            ...processedPages.pageRoutes,
-            ...processedPages.pageApiRoutes,
-          ]
+          const { pageRoutes, pageApiRoutes } = processPageRoutes(
+            mappedPages,
+            dir
+          )
 
           // Build app routes
           if (appDir && mappedAppPages) {
             slots = extractSlotsFromAppRoutes(mappedAppPages)
-            appRoutes = processAppRoutes(mappedAppPages, dir)
+            const result = processAppRoutes(mappedAppPages, validFileMatcher)
+            appRoutes = result.appRoutes
+            appRouteHandlers = result.appRouteHandlers
           }
 
           // Build app layouts
@@ -1343,13 +1344,16 @@ export default async function build(
             dir,
             pageRoutes,
             appRoutes,
+            appRouteHandlers,
+            pageApiRoutes,
             layoutRoutes,
             slots,
             redirects: config.redirects,
             rewrites: config.rewrites,
           })
 
           await writeRouteTypesManifest(routeTypesManifest, routeTypesFilePath)
+          await writeValidatorFile(routeTypesManifest, validatorFilePath)
         })
 
       // Turbopack already handles conflicting app and page routes.

packages/next/src/cli/next-typegen.ts

@@ -27,6 +27,7 @@ import {
   createRouteTypesManifest,
   writeRouteTypesManifest,
 } from '../server/lib/router-utils/route-types-utils'
+import { createValidFileMatcher } from '../server/lib/find-page-file'
 
 export type NextTypegenOptions = {
   dir?: string
@@ -65,10 +66,11 @@ const nextTypegen = async (
 
   let pageRoutes: RouteInfo[] = []
   let appRoutes: RouteInfo[] = []
+  let appRouteHandlers: RouteInfo[] = []
   let layoutRoutes: RouteInfo[] = []
   let slots: SlotInfo[] = []
 
-  let _pageApiRoutes: RouteInfo[] = []
+  let pageApiRoutes: RouteInfo[] = []
 
   let mappedPages: { [page: string]: string } = {}
   let mappedAppPages: { [page: string]: string } = {}
@@ -85,35 +87,39 @@ const nextTypegen = async (
       appDir,
     })
 
+  const validFileMatcher = createValidFileMatcher(
+    nextConfig.pageExtensions,
+    appDir
+  )
+
   // Build pages routes
   if (pagesDir) {
-    const pagePaths = await collectPagesFiles(
-      pagesDir,
-      nextConfig.pageExtensions
-    )
+    const pagePaths = await collectPagesFiles(pagesDir, validFileMatcher)
 
     mappedPages = await createMapping(pagePaths, PAGE_TYPES.PAGES)
 
     // Process pages routes
     const processedPages = processPageRoutes(mappedPages, baseDir)
     pageRoutes = processedPages.pageRoutes
-    _pageApiRoutes = processedPages.pageApiRoutes
+    pageApiRoutes = processedPages.pageApiRoutes
   }
 
   // Build app routes
   if (appDir) {
     // Collect both app pages and layouts in a single directory traversal
     const { appPaths, layoutPaths } = await collectAppFiles(
       appDir,
-      nextConfig.pageExtensions
+      validFileMatcher
     )
 
     mappedAppPages = await createMapping(appPaths, PAGE_TYPES.APP)
     mappedAppLayouts = await createMapping(layoutPaths, PAGE_TYPES.APP)
 
     // Process app routes and extract slots
     slots = extractSlotsFromAppRoutes(mappedAppPages)
-    appRoutes = processAppRoutes(mappedAppPages, baseDir)
+    const result = processAppRoutes(mappedAppPages, validFileMatcher)
+    appRoutes = result.appRoutes
+    appRouteHandlers = result.appRouteHandlers
 
     // Process layout routes
     layoutRoutes = processLayoutRoutes(mappedAppLayouts, baseDir)
@@ -123,6 +129,8 @@ const nextTypegen = async (
     dir: baseDir,
     pageRoutes,
     appRoutes,
+    appRouteHandlers,
+    pageApiRoutes,
     layoutRoutes,
     slots,
     redirects: nextConfig.redirects,

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

@@ -61,8 +61,10 @@ export async function writeAppTypeDeclarations({
     distDir.replaceAll(path.win32.sep, path.posix.sep),
     'types/routes.d.ts'
   )
+  const validatorPath = routeTypesPath.replace(/routes\.d\.ts$/, 'validator.ts')
 
   directives.push(`/// <reference path="./${routeTypesPath}" />`)
+  directives.push(`/// <reference path="./${validatorPath}" />`)
 
   // Push the notice in.
   directives.push(

packages/next/src/server/lib/find-page-file.ts

@@ -90,6 +90,10 @@ export function createValidFileMatcher(
       pageExtensions
     )}$`
   )
+
+  const leafOnlyRouteFileRegex = new RegExp(
+    `(^route|[\\\\/]route)\\.${getExtensionRegexString(pageExtensions)}$`
+  )
   const leafOnlyLayoutFileRegex = new RegExp(
     `(^(layout)|[\\\\/](layout))\\.${getExtensionRegexString(pageExtensions)}$`
   )
@@ -126,6 +130,11 @@ export function createValidFileMatcher(
     return leafOnlyPageFileRegex.test(filePath) || isMetadataFile(filePath)
   }
 
+  // Determine if the file is leaf node route file under app directory
+  function isAppRouterRoute(filePath: string) {
+    return leafOnlyRouteFileRegex.test(filePath)
+  }
+
   function isAppLayoutPage(filePath: string) {
     return leafOnlyLayoutFileRegex.test(filePath)
   }
@@ -148,6 +157,7 @@ export function createValidFileMatcher(
   return {
     isPageFile,
     isAppRouterPage,
+    isAppRouterRoute,
     isAppLayoutPage,
     isMetadataFile,
     isRootNotFound,