Unverified Commit f88de0d8 authored by Ben Gubler's avatar Ben Gubler Committed by GitHub

feat: type guard file generation (#81400)

## Overview
Generates `.next/types/validator.ts` - a single TypeScript file that
validates all route exports using the `satisfies` operator. Replaces the
old `next-types-plugin` webpack plugin.

## Why needed
- **Turbopack compatibility**: Old webpack plugin didn't work with
Turbopack
- **Performance**: Single large file vs hundreds of small validation
files
- **Type safety**: Catches invalid exports like `dynamic =
'invalid-value'`

## Validation Structure
```typescript
// Type definitions
type PageConfig = {
  default: React.ComponentType<any>
  config?: {}
  generateMetadata?: (props: any, parent: any) => Promise<any> | any
  dynamic?: 'auto' | 'force-dynamic' | 'error' | 'force-static'
  // ... other Next.js exports
}

// Validation checks

// Validate app/page.tsx
{
  const handler = {} as typeof import("../../app/page")
  handler satisfies PageConfig
}
...
```

## Example Usage
```typescript
// app/blog/[slug]/page.tsx
export const dynamic = 'some-random-string' // ← Type error caught!

export default async function BlogPostPage(props: PageProps<'/blog/[slug]'>) {
  const params = await props.params
  return <div>Blog Post: {params.slug}</div>
}
```

## Key Benefits
- **Build-time validation**: Catches invalid route exports during
TypeScript compilation
- **Turbopack support**: Works with both webpack and Turbopack
- **Better performance**: One file instead of hundreds of small type
guard files
parent 7a6ee79a
......@@ -76,37 +76,36 @@ 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
* Collect app pages, layouts, and default files from the app directory
* @param appDir - The app directory path
* @param pageExtensions - The configured page extensions
* @param options - Optional configuration
* @returns Object containing appPaths and layoutPaths arrays
* @param validFileMatcher - File matcher object
* @returns Object containing appPaths, layoutPaths, and defaultPaths arrays
*/
export async function collectAppFiles(
appDir: string,
pageExtensions: PageExtensions
validFileMatcher: ReturnType<typeof createValidFileMatcher>
): Promise<{
appPaths: string[]
layoutPaths: string[]
defaultPaths: string[]
}> {
const validFileMatcher = createValidFileMatcher(pageExtensions, appDir)
// Collect both app pages and layouts in a single directory traversal
// Collect app pages, layouts, and default files in a single directory traversal
const allAppFiles = await recursiveReadDir(appDir, {
pathnameFilter: (absolutePath) =>
validFileMatcher.isAppRouterPage(absolutePath) ||
validFileMatcher.isRootNotFound(absolutePath) ||
validFileMatcher.isAppLayoutPage(absolutePath),
validFileMatcher.isAppLayoutPage(absolutePath) ||
validFileMatcher.isAppDefaultPage(absolutePath),
ignorePartFilter: (part) => part.startsWith('_'),
})
// Separate app pages from layouts
// Separate app pages, layouts, and defaults
const appPaths = allAppFiles.filter(
(absolutePath) =>
validFileMatcher.isAppRouterPage(absolutePath) ||
......@@ -115,26 +114,25 @@ export async function collectAppFiles(
const layoutPaths = allAppFiles.filter((absolutePath) =>
validFileMatcher.isAppLayoutPage(absolutePath)
)
const defaultPaths = allAppFiles.filter((absolutePath) =>
validFileMatcher.isAppDefaultPage(absolutePath)
)
return { appPaths, layoutPaths }
return { appPaths, layoutPaths, defaultPaths }
}
/**
* Collect pages from the pages directory
* @param pagesDir - The pages directory path
* @param pageExtensions - The configured page extensions
* @param validFileMatcher - File matcher object
* @returns Array of page file paths
*/
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,
})
}
......@@ -154,18 +152,21 @@ export type SlotInfo = {
* @param baseDir - The base directory path
* @param filePath - The mapped file path (with private prefix)
* @param prefix - The directory prefix ('pages' or 'app')
* @param isSrcDir - Whether the project uses src directory structure
* @returns The relative file path
*/
export function createRelativeFilePath(
baseDir: string,
filePath: string,
prefix: 'pages' | 'app'
prefix: 'pages' | 'app',
isSrcDir: boolean
): string {
const privatePrefix =
prefix === 'pages' ? 'private-next-pages' : 'private-next-app-dir'
const srcPrefix = isSrcDir ? 'src/' : ''
return join(
baseDir,
filePath.replace(new RegExp(`^${privatePrefix}/`), `${prefix}/`)
filePath.replace(new RegExp(`^${privatePrefix}/`), `${srcPrefix}${prefix}/`)
)
}
......@@ -173,11 +174,13 @@ export function createRelativeFilePath(
* Process pages routes from mapped pages
* @param mappedPages - The mapped pages object
* @param baseDir - The base directory path
* @param isSrcDir - Whether the project uses src directory structure
* @returns Object containing pageRoutes and pageApiRoutes
*/
export function processPageRoutes(
mappedPages: { [page: string]: string },
baseDir: string
baseDir: string,
isSrcDir: boolean
): {
pageRoutes: RouteInfo[]
pageApiRoutes: RouteInfo[]
......@@ -186,7 +189,12 @@ export function processPageRoutes(
const pageApiRoutes: RouteInfo[] = []
for (const [route, filePath] of Object.entries(mappedPages)) {
const relativeFilePath = createRelativeFilePath(baseDir, filePath, 'pages')
const relativeFilePath = createRelativeFilePath(
baseDir,
filePath,
'pages',
isSrcDir
)
if (route.startsWith('/api/')) {
pageApiRoutes.push({
......@@ -243,46 +251,129 @@ export function extractSlotsFromAppRoutes(mappedAppPages: {
return slots
}
/**
* Extract slots from default files
* @param mappedDefaultFiles - The mapped default files object
* @returns Array of slot information
*/
export function extractSlotsFromDefaultFiles(mappedDefaultFiles: {
[page: string]: string
}): SlotInfo[] {
const slots: SlotInfo[] = []
for (const [route] of Object.entries(mappedDefaultFiles)) {
const segments = route.split('/')
for (let i = segments.length - 1; i >= 0; i--) {
const segment = segments[i]
if (isParallelRouteSegment(segment)) {
const parentPath = normalizeAppPath(segments.slice(0, i).join('/'))
const slotName = segment.slice(1)
// Check if the slot already exists
if (slots.some((s) => s.name === slotName && s.parent === parentPath))
continue
slots.push({
name: slotName,
parent: parentPath,
})
break
}
}
}
return slots
}
/**
* Combine and deduplicate slot arrays using a Set
* @param slotArrays - Arrays of slot information to combine
* @returns Deduplicated array of slots
*/
export function combineSlots(...slotArrays: SlotInfo[][]): SlotInfo[] {
const slotSet = new Set<string>()
const result: SlotInfo[] = []
for (const slots of slotArrays) {
for (const slot of slots) {
const key = `${slot.name}:${slot.parent}`
if (!slotSet.has(key)) {
slotSet.add(key)
result.push(slot)
}
}
}
return result
}
/**
* Process app routes from mapped app pages
* @param mappedAppPages - The mapped app pages object
* @param validFileMatcher - File matcher object
* @param baseDir - The base directory path
* @param isSrcDir - Whether the project uses src directory structure
* @returns Array of route information
*/
export function processAppRoutes(
mappedAppPages: { [page: string]: string },
baseDir: string
): RouteInfo[] {
validFileMatcher: ReturnType<typeof createValidFileMatcher>,
baseDir: string,
isSrcDir: boolean
): {
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')
const relativeFilePath = createRelativeFilePath(
baseDir,
filePath,
'app',
isSrcDir
)
appRoutes.push({
route: normalizeAppPath(normalizePathSep(route)),
filePath: relativeFilePath,
})
if (validFileMatcher.isAppRouterRoute(filePath)) {
appRouteHandlers.push({
route: normalizeAppPath(normalizePathSep(route)),
filePath: relativeFilePath,
})
} else {
appRoutes.push({
route: normalizeAppPath(normalizePathSep(route)),
filePath: relativeFilePath,
})
}
}
return appRoutes
return { appRoutes, appRouteHandlers }
}
/**
* Process layout routes from mapped app layouts
* @param mappedAppLayouts - The mapped app layouts object
* @param baseDir - The base directory path
* @param isSrcDir - Whether the project uses src directory structure
* @returns Array of layout route information
*/
export function processLayoutRoutes(
mappedAppLayouts: { [page: string]: string },
baseDir: string
baseDir: string,
isSrcDir: boolean
): RouteInfo[] {
const layoutRoutes: RouteInfo[] = []
for (const [route, filePath] of Object.entries(mappedAppLayouts)) {
const relativeFilePath = createRelativeFilePath(baseDir, filePath, 'app')
const relativeFilePath = createRelativeFilePath(
baseDir,
filePath,
'app',
isSrcDir
)
layoutRoutes.push({
route: ensureLeadingSlash(
normalizeAppPath(normalizePathSep(route)).replace(/\/layout$/, '')
......
......@@ -115,8 +115,11 @@ import {
processAppRoutes,
processLayoutRoutes,
extractSlotsFromAppRoutes,
extractSlotsFromDefaultFiles,
combineSlots,
type RouteInfo,
type SlotInfo,
collectPagesFiles,
} from './entries'
import { PAGE_TYPES } from '../lib/page-types'
import { generateBuildId } from './generate-build-id'
......@@ -145,7 +148,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 +220,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
......@@ -1120,11 +1124,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(
......@@ -1190,16 +1192,18 @@ 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
// Collect app pages, layouts, and default files 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
// Note: defaultPaths are not used in the build process, only for slot detection in generating route types
}
mappedAppPages = await nextBuildSpan
......@@ -1280,40 +1284,77 @@ 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,
isSrcDir
)
// Build app routes
if (appDir && mappedAppPages) {
slots = extractSlotsFromAppRoutes(mappedAppPages)
appRoutes = processAppRoutes(mappedAppPages, dir)
// Extract slots from both pages and default files
const slotsFromPages = extractSlotsFromAppRoutes(mappedAppPages)
let slotsFromDefaults: SlotInfo[] = []
// Collect and map default files for slot extraction
const { defaultPaths } = await nextBuildSpan
.traceChild('collect-default-files')
.traceAsyncFn(() => collectAppFiles(appDir, validFileMatcher))
if (defaultPaths.length > 0) {
const mappedDefaultFiles = await nextBuildSpan
.traceChild('create-default-mapping')
.traceAsyncFn(() =>
createPagesMapping({
pagePaths: defaultPaths,
isDev: false,
pagesType: PAGE_TYPES.APP,
pageExtensions: config.pageExtensions,
pagesDir,
appDir,
})
)
slotsFromDefaults =
extractSlotsFromDefaultFiles(mappedDefaultFiles)
}
// Combine slots and deduplicate using Set
slots = combineSlots(slotsFromPages, slotsFromDefaults)
const result = processAppRoutes(
mappedAppPages,
validFileMatcher,
dir,
isSrcDir
)
appRoutes = result.appRoutes
appRouteHandlers = result.appRouteHandlers
}
// Build app layouts
if (appDir && mappedAppLayouts) {
layoutRoutes = processLayoutRoutes(mappedAppLayouts, dir)
layoutRoutes = processLayoutRoutes(mappedAppLayouts, dir, isSrcDir)
}
const routeTypesManifest = await createRouteTypesManifest({
dir,
pageRoutes,
appRoutes,
appRouteHandlers,
pageApiRoutes,
layoutRoutes,
slots,
redirects: config.redirects,
rewrites: config.rewrites,
validatorFilePath,
})
await writeRouteTypesManifest(
......@@ -1321,6 +1362,7 @@ export default async function build(
routeTypesFilePath,
config
)
await writeValidatorFile(routeTypesManifest, validatorFilePath)
})
// Turbopack already handles conflicting app and page routes.
......
#!/usr/bin/env node
import { existsSync } from 'fs'
import { join } from 'path'
import path, { join } from 'path'
import { mkdir } from 'fs/promises'
import loadConfig from '../server/config'
......@@ -18,6 +18,8 @@ import {
processAppRoutes,
processLayoutRoutes,
extractSlotsFromAppRoutes,
extractSlotsFromDefaultFiles,
combineSlots,
type RouteInfo,
type SlotInfo,
} from '../build/entries'
......@@ -26,7 +28,9 @@ import { PAGE_TYPES } from '../lib/page-types'
import {
createRouteTypesManifest,
writeRouteTypesManifest,
writeValidatorFile,
} from '../server/lib/router-utils/route-types-utils'
import { createValidFileMatcher } from '../server/lib/find-page-file'
export type NextTypegenOptions = {
dir?: string
......@@ -61,14 +65,16 @@ const nextTypegen = async (
console.log('Generating route types...')
const routeTypesFilePath = join(distDir, 'types', 'routes.d.ts')
const validatorFilePath = join(distDir, 'types', 'validator.ts')
await mkdir(join(distDir, 'types'), { recursive: true })
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,48 +91,70 @@ const nextTypegen = async (
appDir,
})
const validFileMatcher = createValidFileMatcher(
nextConfig.pageExtensions,
appDir
)
const isSrcDir = path
.relative(baseDir, pagesDir || appDir || '')
.startsWith('src')
// 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)
const processedPages = processPageRoutes(mappedPages, baseDir, isSrcDir)
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(
// Collect app pages, layouts, and default files in a single directory traversal
const { appPaths, layoutPaths, defaultPaths } = await collectAppFiles(
appDir,
nextConfig.pageExtensions
validFileMatcher
)
mappedAppPages = await createMapping(appPaths, PAGE_TYPES.APP)
mappedAppLayouts = await createMapping(layoutPaths, PAGE_TYPES.APP)
const mappedDefaultFiles = await createMapping(defaultPaths, PAGE_TYPES.APP)
// Process app routes and extract slots
slots = extractSlotsFromAppRoutes(mappedAppPages)
appRoutes = processAppRoutes(mappedAppPages, baseDir)
// Process app routes and extract slots from both pages and default files
const slotsFromPages = extractSlotsFromAppRoutes(mappedAppPages)
const slotsFromDefaults = extractSlotsFromDefaultFiles(mappedDefaultFiles)
// Combine slots and deduplicate using Set
slots = combineSlots(slotsFromPages, slotsFromDefaults)
const result = processAppRoutes(
mappedAppPages,
validFileMatcher,
baseDir,
isSrcDir
)
appRoutes = result.appRoutes
appRouteHandlers = result.appRouteHandlers
// Process layout routes
layoutRoutes = processLayoutRoutes(mappedAppLayouts, baseDir)
layoutRoutes = processLayoutRoutes(mappedAppLayouts, baseDir, isSrcDir)
}
const routeTypesManifest = await createRouteTypesManifest({
dir: baseDir,
pageRoutes,
appRoutes,
appRouteHandlers,
pageApiRoutes,
layoutRoutes,
slots,
redirects: nextConfig.redirects,
rewrites: nextConfig.rewrites,
validatorFilePath,
})
await writeRouteTypesManifest(
......@@ -135,6 +163,8 @@ const nextTypegen = async (
nextConfig
)
await writeValidatorFile(routeTypesManifest, validatorFilePath)
console.log('✓ Route types generated successfully')
}
......
......@@ -90,12 +90,19 @@ export function createValidFileMatcher(
pageExtensions
)}$`
)
const leafOnlyRouteFileRegex = new RegExp(
`(^route|[\\\\/]route)\\.${getExtensionRegexString(pageExtensions)}$`
)
const leafOnlyLayoutFileRegex = new RegExp(
`(^(layout)|[\\\\/](layout))\\.${getExtensionRegexString(pageExtensions)}$`
)
const rootNotFoundFileRegex = new RegExp(
`^not-found\\.${getExtensionRegexString(pageExtensions)}$`
)
const leafOnlyDefaultFileRegex = new RegExp(
`(^(default)|[\\\\/](default))\\.${getExtensionRegexString(pageExtensions)}$`
)
/** TODO-METADATA: support other metadata routes
* regex for:
*
......@@ -126,10 +133,19 @@ 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)
}
function isAppDefaultPage(filePath: string) {
return leafOnlyDefaultFileRegex.test(filePath)
}
function isPageFile(filePath: string) {
return validExtensionFileRegex.test(filePath) || isMetadataFile(filePath)
}
......@@ -148,7 +164,9 @@ export function createValidFileMatcher(
return {
isPageFile,
isAppRouterPage,
isAppRouterRoute,
isAppLayoutPage,
isAppDefaultPage,
isMetadataFile,
isRootNotFound,
}
......
......@@ -4,10 +4,18 @@ import {
type Group,
} from '../../../shared/lib/router/utils/route-regex'
import type { NextConfigComplete } from '../../config-shared'
import { isParallelRouteSegment } from '../../../shared/lib/segment'
import fs from 'fs'
import { generateRouteTypesFile, generateLinkTypesFile } from './typegen'
import {
generateRouteTypesFile,
generateLinkTypesFile,
generateValidatorFile,
} from './typegen'
import { tryToParsePath } from '../../../lib/try-to-parse-path'
import {
extractInterceptionRouteInformation,
isInterceptionRouteAppPath,
} from '../../../shared/lib/router/utils/interception-routes'
interface RouteInfo {
path: string
......@@ -18,10 +26,19 @@ export interface RouteTypesManifest {
appRoutes: Record<string, RouteInfo>
pageRoutes: Record<string, RouteInfo>
layoutRoutes: Record<string, RouteInfo & { slots: string[] }>
appRouteHandlerRoutes: Record<string, RouteInfo>
/** Map of redirect source => RouteInfo */
redirectRoutes: Record<string, RouteInfo>
/** Map of rewrite source => RouteInfo */
rewriteRoutes: Record<string, RouteInfo>
/** File paths for validation */
appPagePaths: Set<string>
pagesRouterPagePaths: Set<string>
layoutPaths: Set<string>
appRouteHandlers: Set<string>
pageApiRoutes: Set<string>
/** Direct mapping from file paths to routes for validation */
filePathToRoute: Map<string, string>
}
// Convert a custom-route source string (`/blog/:slug`, `/docs/:path*`, ...)
......@@ -102,22 +119,20 @@ export function extractRouteParams(route: string) {
return regex.groups
}
function isCanonicalRoute(route: string) {
const segments = route.split('/')
for (let i = segments.length - 1; i >= 0; i--) {
const segment = segments[i]
if (
isParallelRouteSegment(segment) ||
segment.startsWith('(.)') ||
segment.startsWith('(..)') ||
segment.startsWith('(...)')
) {
return false
}
/**
* Resolves an intercepting route to its canonical equivalent
* Example: /gallery/test/(..)photo/[id] -> /gallery/photo/[id]
*/
function resolveInterceptingRoute(route: string): string {
// Reuse centralized interception route normalization logic
try {
if (!isInterceptionRouteAppPath(route)) return route
const { interceptedRoute } = extractInterceptionRouteInformation(route)
return interceptedRoute
} catch {
// If parsing fails, fall back to the original route
return route
}
return true
}
/**
......@@ -128,43 +143,88 @@ export async function createRouteTypesManifest({
dir,
pageRoutes,
appRoutes,
appRouteHandlers,
pageApiRoutes,
layoutRoutes,
slots,
redirects,
rewrites,
validatorFilePath,
}: {
dir: string
pageRoutes: Array<{ route: string; filePath: string }>
appRoutes: Array<{ route: string; filePath: string }>
appRouteHandlers: Array<{ route: string; filePath: string }>
pageApiRoutes: Array<{ route: string; filePath: string }>
layoutRoutes: Array<{ route: string; filePath: string }>
slots: Array<{ name: string; parent: string }>
redirects?: NextConfigComplete['redirects']
rewrites?: NextConfigComplete['rewrites']
validatorFilePath?: string
}): Promise<RouteTypesManifest> {
// Helper function to calculate the correct relative path
const getRelativePath = (filePath: string) => {
if (validatorFilePath) {
// For validator generation, calculate path relative to validator directory
return path.relative(path.dirname(validatorFilePath), filePath)
}
// For other uses, calculate path relative to project directory
return path.relative(dir, filePath)
}
const manifest: RouteTypesManifest = {
appRoutes: {},
pageRoutes: {},
layoutRoutes: {},
appRouteHandlerRoutes: {},
redirectRoutes: {},
rewriteRoutes: {},
appRouteHandlers: new Set(appRouteHandlers.map(({ filePath }) => filePath)),
pageApiRoutes: new Set(pageApiRoutes.map(({ filePath }) => filePath)),
appPagePaths: new Set(appRoutes.map(({ filePath }) => filePath)),
pagesRouterPagePaths: new Set(pageRoutes.map(({ filePath }) => filePath)),
layoutPaths: new Set(layoutRoutes.map(({ filePath }) => filePath)),
filePathToRoute: new Map([
...appRoutes.map(
({ route, filePath }) =>
[filePath, resolveInterceptingRoute(route)] as [string, string]
),
...layoutRoutes.map(
({ route, filePath }) =>
[filePath, resolveInterceptingRoute(route)] as [string, string]
),
...appRouteHandlers.map(
({ route, filePath }) =>
[filePath, resolveInterceptingRoute(route)] as [string, string]
),
...pageRoutes.map(
({ route, filePath }) => [filePath, route] as [string, string]
),
...pageApiRoutes.map(
({ route, filePath }) => [filePath, route] as [string, string]
),
]),
}
// Process page routes
for (const { route, filePath } of pageRoutes) {
manifest.pageRoutes[route] = {
path: path.relative(dir, filePath),
path: getRelativePath(filePath),
groups: extractRouteParams(route),
}
}
// Process layout routes
for (const { route, filePath } of layoutRoutes) {
if (!isCanonicalRoute(route)) continue
// Use the resolved route (for interception routes, this gives us the canonical route)
const resolvedRoute = resolveInterceptingRoute(route)
manifest.layoutRoutes[route] = {
path: path.relative(dir, filePath),
groups: extractRouteParams(route),
slots: [],
if (!manifest.layoutRoutes[resolvedRoute]) {
manifest.layoutRoutes[resolvedRoute] = {
path: getRelativePath(filePath),
groups: extractRouteParams(resolvedRoute),
slots: [],
}
}
}
......@@ -177,11 +237,37 @@ export async function createRouteTypesManifest({
// Process app routes
for (const { route, filePath } of appRoutes) {
if (!isCanonicalRoute(route)) continue
// Don't include metadata routes or pages
if (
!filePath.endsWith('page.ts') &&
!filePath.endsWith('page.tsx') &&
!filePath.endsWith('.mdx') &&
!filePath.endsWith('.md')
) {
continue
}
manifest.appRoutes[route] = {
path: path.relative(dir, filePath),
groups: extractRouteParams(route),
// Use the resolved route (for interception routes, this gives us the canonical route)
const resolvedRoute = resolveInterceptingRoute(route)
if (!manifest.appRoutes[resolvedRoute]) {
manifest.appRoutes[resolvedRoute] = {
path: getRelativePath(filePath),
groups: extractRouteParams(resolvedRoute),
}
}
}
// Process app route handlers
for (const { route, filePath } of appRouteHandlers) {
// Use the resolved route (for interception routes, this gives us the canonical route)
const resolvedRoute = resolveInterceptingRoute(route)
if (!manifest.appRouteHandlerRoutes[resolvedRoute]) {
manifest.appRouteHandlerRoutes[resolvedRoute] = {
path: getRelativePath(filePath),
groups: extractRouteParams(resolvedRoute),
}
}
}
......@@ -246,3 +332,16 @@ export async function writeRouteTypesManifest(
await fs.promises.writeFile(linkTypesPath, generateLinkTypesFile(manifest))
}
}
export async function writeValidatorFile(
manifest: RouteTypesManifest,
filePath: string
) {
const dirname = path.dirname(filePath)
if (!fs.existsSync(dirname)) {
await fs.promises.mkdir(dirname, { recursive: true })
}
await fs.promises.writeFile(filePath, generateValidatorFile(manifest))
}
......@@ -87,6 +87,7 @@ import { JSON_CONTENT_TYPE_HEADER } from '../../../lib/constants'
import {
createRouteTypesManifest,
writeRouteTypesManifest,
writeValidatorFile,
} from './route-types-utils'
import { isParallelRouteSegment } from '../../../shared/lib/segment'
import { ensureLeadingSlash } from '../../../shared/lib/page-path/ensure-leading-slash'
......@@ -219,8 +220,15 @@ async function startWatcher(
appRoutes: {},
pageRoutes: {},
layoutRoutes: {},
appRouteHandlerRoutes: {},
redirectRoutes: {},
rewriteRoutes: {},
appPagePaths: new Set(),
pagesRouterPagePaths: new Set(),
layoutPaths: new Set(),
appRouteHandlers: new Set(),
pageApiRoutes: new Set(),
filePathToRoute: new Map(),
},
path.join(distTypesDir, 'routes.d.ts'),
opts.nextConfig
......@@ -335,6 +343,7 @@ async function startWatcher(
let previousConflictingPagePaths: Set<string> = new Set()
const routeTypesFilePath = path.join(distDir, 'types', 'routes.d.ts')
const validatorFilePath = path.join(distDir, 'types', 'validator.ts')
wp.on('aggregated', async () => {
let middlewareMatchers: MiddlewareMatcher[] | undefined
......@@ -345,6 +354,8 @@ async function startWatcher(
const conflictingAppPagePaths = new Set<string>()
const appPageFilePaths = new Map<string, string>()
const pagesPageFilePaths = new Map<string, string>()
const appRouteHandlers: Array<{ route: string; filePath: string }> = []
const pageApiRoutes: Array<{ route: string; filePath: string }> = []
const pageRoutes: Array<{ route: string; filePath: string }> = []
const appRoutes: Array<{ route: string; filePath: string }> = []
......@@ -565,7 +576,10 @@ async function startWatcher(
''
)
),
filePath: fileName,
filePath: path.relative(
path.dirname(validatorFilePath),
fileName
),
})
}
......@@ -589,10 +603,23 @@ async function startWatcher(
appFiles.add(pageName)
}
appRoutes.push({
route: normalizePathSep(pageName),
filePath: fileName,
})
if (validFileMatcher.isAppRouterRoute(fileName)) {
appRouteHandlers.push({
route: normalizePathSep(pageName),
filePath: path.relative(
path.dirname(validatorFilePath),
fileName
),
})
} else {
appRoutes.push({
route: normalizePathSep(pageName),
filePath: path.relative(
path.dirname(validatorFilePath),
fileName
),
})
}
if (routedPages.includes(pageName)) {
continue
......@@ -605,10 +632,23 @@ async function startWatcher(
opts.fsChecker.nextDataRoutes.add(pageName)
}
pageRoutes.push({
route: normalizePathSep(pageName),
filePath: fileName,
})
if (pageName.startsWith('/api/')) {
pageApiRoutes.push({
route: normalizePathSep(pageName),
filePath: path.relative(
path.dirname(validatorFilePath),
fileName
),
})
} else {
pageRoutes.push({
route: normalizePathSep(pageName),
filePath: path.relative(
path.dirname(validatorFilePath),
fileName
),
})
}
}
// Record pages
......@@ -1022,6 +1062,8 @@ async function startWatcher(
slots,
redirects: opts.nextConfig.redirects,
rewrites: opts.nextConfig.rewrites,
appRouteHandlers,
pageApiRoutes,
})
await writeRouteTypesManifest(
......@@ -1029,6 +1071,7 @@ async function startWatcher(
routeTypesFilePath,
opts.nextConfig
)
await writeValidatorFile(routeTypesManifest, validatorFilePath)
}
if (!resolved) {
......
......@@ -10,13 +10,24 @@ function generateRouteTypes(routesManifest: RouteTypesManifest): string {
let result = ''
// Generate AppRoutes union type
// Generate AppRoutes union type (pages only)
if (appRoutes.length > 0) {
result += `type AppRoutes = ${appRoutes.map((route) => JSON.stringify(route)).join(' | ')}\n`
} else {
result += 'type AppRoutes = never\n'
}
// Generate AppRouteHandlerRoutes union type for route handlers
const appRouteHandlerRoutes = Object.keys(
routesManifest.appRouteHandlerRoutes
).sort()
if (appRouteHandlerRoutes.length > 0) {
result += `type AppRouteHandlerRoutes = ${appRouteHandlerRoutes.map((route) => JSON.stringify(route)).join(' | ')}\n`
} else {
result += 'type AppRouteHandlerRoutes = never\n'
}
// Generate PageRoutes union type
if (pageRoutes.length > 0) {
result += `type PageRoutes = ${pageRoutes.map((route) => JSON.stringify(route)).join(' | ')}\n`
......@@ -50,7 +61,7 @@ function generateRouteTypes(routesManifest: RouteTypesManifest): string {
}
result +=
'type Routes = AppRoutes | PageRoutes | LayoutRoutes | RedirectRoutes | RewriteRoutes\n'
'type Routes = AppRoutes | AppRouteHandlerRoutes | PageRoutes | LayoutRoutes | RedirectRoutes | RewriteRoutes\n'
return result
}
......@@ -58,6 +69,7 @@ function generateRouteTypes(routesManifest: RouteTypesManifest): string {
function generateParamTypes(routesManifest: RouteTypesManifest): string {
const allRoutes = {
...routesManifest.appRoutes,
...routesManifest.appRouteHandlerRoutes,
...routesManifest.pageRoutes,
...routesManifest.layoutRoutes,
...routesManifest.redirectRoutes,
......@@ -340,6 +352,169 @@ declare module 'next/form' {
`
}
export function generateValidatorFile(
routesManifest: RouteTypesManifest
): string {
const generateValidations = (
paths: string[],
type:
| 'AppPageConfig'
| 'PagesPageConfig'
| 'LayoutConfig'
| 'RouteHandlerConfig'
| 'ApiRouteConfig',
pathToRouteMap?: Map<string, string>
) =>
paths
.sort()
// Only validate TypeScript files - JavaScript files have too many type inference limitations
.filter(
(filePath) => filePath.endsWith('.ts') || filePath.endsWith('.tsx')
)
.filter(
// Don't include metadata routes or pages
// (e.g. /manifest.webmanifest)
(filePath) =>
type !== 'AppPageConfig' ||
filePath.endsWith('page.ts') ||
filePath.endsWith('page.tsx')
)
.map((filePath) => {
// Keep the file extension for TypeScript imports to support node16 module resolution
const importPath = filePath
const route = pathToRouteMap?.get(filePath)
const typeWithRoute =
route &&
(type === 'AppPageConfig' ||
type === 'LayoutConfig' ||
type === 'RouteHandlerConfig')
? `${type}<${JSON.stringify(route)}>`
: type
return `// Validate ${filePath}
{
const handler = {} as typeof import(${JSON.stringify(importPath)})
handler satisfies ${typeWithRoute}
}`
})
.join('\n\n')
// Use direct mappings from the manifest
// Generate validations for different route types
const appPageValidations = generateValidations(
Array.from(routesManifest.appPagePaths).sort(),
'AppPageConfig',
routesManifest.filePathToRoute
)
const appRouteHandlerValidations = generateValidations(
Array.from(routesManifest.appRouteHandlers).sort(),
'RouteHandlerConfig',
routesManifest.filePathToRoute
)
const pagesRouterPageValidations = generateValidations(
Array.from(routesManifest.pagesRouterPagePaths).sort(),
'PagesPageConfig'
)
const pagesApiRouteValidations = generateValidations(
Array.from(routesManifest.pageApiRoutes).sort(),
'ApiRouteConfig'
)
const layoutValidations = generateValidations(
Array.from(routesManifest.layoutPaths).sort(),
'LayoutConfig',
routesManifest.filePathToRoute
)
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
import type { AppRoutes, AppRouteHandlerRoutes, LayoutRoutes, ParamMap } from "./routes.js"
import type { ResolvingMetadata, ResolvingViewport } from "next/dist/lib/metadata/types/metadata-interface.js"
type AppPageConfig<Route extends AppRoutes = AppRoutes> = {
default: React.ComponentType<{ params: Promise<ParamMap[Route]> } & any> | ((props: { params: Promise<ParamMap[Route]> } & any) => React.ReactNode | Promise<React.ReactNode> | never | void | Promise<void>)
generateStaticParams?: (props: { params: ParamMap[Route] }) => Promise<any[]> | any[]
generateMetadata?: (
props: { params: Promise<ParamMap[Route]> } & any,
parent: ResolvingMetadata
) => Promise<any> | any
generateViewport?: (
props: { params: Promise<ParamMap[Route]> } & any,
parent: ResolvingViewport
) => Promise<any> | any
metadata?: any
viewport?: any
}
type PagesPageConfig = {
default: React.ComponentType<any> | ((props: any) => React.ReactNode | Promise<React.ReactNode> | never | void)
getStaticProps?: (context: any) => Promise<any> | any
getStaticPaths?: (context: any) => Promise<any> | any
getServerSideProps?: (context: any) => Promise<any> | any
getInitialProps?: (context: any) => Promise<any> | any
/**
* Segment configuration for legacy Pages Router pages.
* Validated at build-time by parsePagesSegmentConfig.
*/
config?: {
amp?: boolean | 'hybrid'
maxDuration?: number
runtime?: 'edge' | 'experimental-edge' | 'nodejs' | string // necessary unless config is exported as const
regions?: string[]
}
}
type LayoutConfig<Route extends LayoutRoutes = LayoutRoutes> = {
default: React.ComponentType<LayoutProps<Route>> | ((props: LayoutProps<Route>) => React.ReactNode | Promise<React.ReactNode> | never | void | Promise<void>)
generateStaticParams?: (props: { params: ParamMap[Route] }) => Promise<any[]> | any[]
generateMetadata?: (
props: { params: Promise<ParamMap[Route]> } & any,
parent: ResolvingMetadata
) => Promise<any> | any
generateViewport?: (
props: { params: Promise<ParamMap[Route]> } & any,
parent: ResolvingViewport
) => Promise<any> | any
metadata?: any
viewport?: any
}
type RouteHandlerConfig<Route extends AppRouteHandlerRoutes = AppRouteHandlerRoutes> = {
GET?: (request: Request, context: { params: Promise<ParamMap[Route]> }) => Promise<Response> | Response | Promise<void> | void
POST?: (request: Request, context: { params: Promise<ParamMap[Route]> }) => Promise<Response> | Response | Promise<void> | void
PUT?: (request: Request, context: { params: Promise<ParamMap[Route]> }) => Promise<Response> | Response | Promise<void> | void
PATCH?: (request: Request, context: { params: Promise<ParamMap[Route]> }) => Promise<Response> | Response | Promise<void> | void
DELETE?: (request: Request, context: { params: Promise<ParamMap[Route]> }) => Promise<Response> | Response | Promise<void> | void
HEAD?: (request: Request, context: { params: Promise<ParamMap[Route]> }) => Promise<Response> | Response | Promise<void> | void
OPTIONS?: (request: Request, context: { params: Promise<ParamMap[Route]> }) => Promise<Response> | Response | Promise<void> | void
}
type ApiRouteConfig = {
default: (req: any, res: any) => Promise<void> | void | Promise<Response> | Response
config?: {
api?: {
bodyParser?: boolean | { sizeLimit?: string }
responseLimit?: string | number
externalResolver?: boolean
}
runtime?: 'edge' | 'experimental-edge' | 'nodejs' | string // necessary unless config is exported as const
maxDuration?: number
}
}
${appPageValidations}
${appRouteHandlerValidations}
${pagesRouterPageValidations}
${pagesApiRouteValidations}
${layoutValidations}
`
}
export function generateRouteTypesFile(
routesManifest: RouteTypesManifest
): string {
......@@ -358,7 +533,7 @@ export type ParamsOf<Route extends Routes> = ParamMap[Route]
${layoutSlotMap}
export type { AppRoutes, PageRoutes, LayoutRoutes, RedirectRoutes, RewriteRoutes }
export type { AppRoutes, AppRouteHandlerRoutes, PageRoutes, LayoutRoutes, RedirectRoutes, RewriteRoutes, ParamMap }
declare global {
/**
......
......@@ -5,7 +5,7 @@ export default function page() {
export async function generateStaticParams({
params,
}: {
params: { slug: 'a' | 'b' }
params: { slug: string }
}) {
console.log(params)
return []
......
export default function Root(props: LayoutProps<'/'>) {
return (
<html>
<body>{props.children}</body>
</html>
)
}
export default function Page(props: PageProps<'/'>) {
return <p>hello world</p>
}
export async function GET() {
return Response.json({ message: 'Hello World' })
}
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {}
module.exports = nextConfig
export default function AboutPage() {
return <div>About Page</div>
}
import type { NextApiRequest, NextApiResponse } from 'next/types'
type ResponseData = {
message: string
}
export default function handler(
req: NextApiRequest,
res: NextApiResponse<ResponseData>
) {
res.status(200).json({ message: 'Hello from Next.js!' })
}
import { nextTestSetup } from 'e2e-utils'
describe('typed-routes-validator', () => {
const { next, isNextStart, skipped } = nextTestSetup({
files: __dirname,
skipDeployment: true,
})
if (skipped) {
return
}
it('should generate route validation correctly', async () => {
const dts = await next.readFile('.next/types/validator.ts')
expect(dts).toMatch(
/const handler = {} as typeof import\(".*\/app\/page.tsx"\)\s+handler satisfies AppPageConfig<"\/">/
)
expect(dts).toMatch(
/const handler = {} as typeof import\(".*\/app\/send-email\/route.ts"\)\s+handler satisfies RouteHandlerConfig<"\/send-email">/
)
expect(dts).toMatch(
/const handler = {} as typeof import\(".*\/pages\/about.tsx"\)\s+handler satisfies PagesPageConfig/
)
expect(dts).toMatch(
/const handler = {} as typeof import\(".*\/pages\/api\/test-route.ts"\)\s+handler satisfies ApiRouteConfig/
)
expect(dts).toMatch(
/const handler = {} as typeof import\(".*\/app\/layout.tsx"\)\s+handler satisfies LayoutConfig<"\/">/
)
})
if (isNextStart) {
it('should pass type checking with valid page exports', async () => {
await next.stop()
await next.patchFile(
'app/test-page.tsx',
`
export default function TestPage() {
return <div>Test Page</div>
}
export const dynamic = 'force-static'
export const metadata = { title: 'Test' }
`
)
const { exitCode } = await next.build()
expect(exitCode).toBe(0)
})
it('should fail type checking with invalid page exports', async () => {
await next.stop()
await next.patchFile(
'app/invalid/page.tsx',
`
// Missing default export
export const metadata = { title: 'Invalid' }
`
)
const { exitCode, cliOutput } = await next.build()
// clean up before assertion just in case it fails
await next.deleteFile('app/invalid/page.tsx')
expect(exitCode).toBe(1)
expect(cliOutput).toMatch(
/Type error: Type 'typeof import\(.*\)' does not satisfy the expected type 'AppPageConfig<"\/invalid">'/
)
})
it('should pass type checking with valid route handler exports', async () => {
await next.stop()
await next.patchFile(
'app/valid/route.ts',
`
export async function GET() {
return new Response('OK')
}
export async function POST(request: Request) {
return new Response('Created', { status: 201 })
}
export const dynamic = 'force-dynamic'
`
)
const { exitCode } = await next.build()
expect(exitCode).toBe(0)
})
it('should fail type checking with invalid route handler exports', async () => {
await next.stop()
await next.patchFile(
'app/invalid/route.ts',
`
// Invalid signature - missing Response return type
export function GET() {
return 'not a response'
}
`
)
const { exitCode, cliOutput } = await next.build()
// clean up before assertion just in case it fails
await next.deleteFile('app/invalid/route.ts')
expect(exitCode).toBe(1)
expect(cliOutput).toMatch(
/Type error: Type 'typeof import.*does not satisfy the expected type 'RouteHandlerConfig<"\/invalid">'/
)
})
it('should pass type checking with valid layout exports', async () => {
await next.stop()
await next.patchFile(
'app/test/layout.tsx',
`
export default function TestLayout({
children,
}: {
children: React.ReactNode
}) {
return <div>{children}</div>
}
export const metadata = { title: 'Test Layout' }
`
)
const { exitCode } = await next.build()
expect(exitCode).toBe(0)
})
it('should fail type checking with invalid layout exports', async () => {
await next.stop()
await next.patchFile(
'app/invalid/layout.tsx',
`
// Invalid - doesn't return a React node
export default function InvalidLayout() {
return {randomKey: 'randomValue'}
}
`
)
const { exitCode, cliOutput } = await next.build()
// clean up before assertion just in case it fails
await next.deleteFile('app/invalid/layout.tsx')
expect(exitCode).toBe(1)
expect(cliOutput).toMatch(
/Type error: Type 'typeof import\(.*does not satisfy the expected type 'LayoutConfig<"\/invalid">'/
)
})
it('should pass type checking with valid API route exports', async () => {
await next.stop()
await next.patchFile(
'pages/api/valid-api.ts',
`
import type { NextApiRequest, NextApiResponse } from 'next'
export default function handler(
req: NextApiRequest,
res: NextApiResponse
) {
res.status(200).json({ message: 'OK' })
}
export const config = {
api: {
bodyParser: true,
},
}
`
)
const { exitCode } = await next.build()
expect(exitCode).toBe(0)
})
it('should fail type checking with invalid API route exports', async () => {
await next.stop()
await next.patchFile(
'pages/api/invalid-api.ts',
`
// Invalid - not a function
export default { message: 'not a function' }
`
)
const { exitCode, cliOutput } = await next.build()
// clean up before assertion just in case it fails
await next.deleteFile('pages/api/invalid-api.ts')
expect(exitCode).toBe(1)
expect(cliOutput).toMatch(
/Type error: Type 'typeof import\(.*does not satisfy the expected type 'ApiRouteConfig'/
)
})
}
})
......@@ -2,11 +2,12 @@ import { nextTestSetup } from 'e2e-utils'
const expectedDts = `
type AppRoutes = "/" | "/_shop/[[...category]]" | "/dashboard" | "/dashboard/settings" | "/docs/[...slug]" | "/gallery/photo/[id]" | "/project/[slug]"
type AppRouteHandlerRoutes = never
type PageRoutes = "/about" | "/users/[id]"
type LayoutRoutes = "/" | "/dashboard"
type RedirectRoutes = "/blog/[category]/[[...slug]]" | "/project/[slug]"
type RewriteRoutes = "/api-legacy/[version]/[[...endpoint]]" | "/docs-old/[...path]"
type Routes = AppRoutes | PageRoutes | LayoutRoutes | RedirectRoutes | RewriteRoutes
type Routes = AppRoutes | AppRouteHandlerRoutes | PageRoutes | LayoutRoutes | RedirectRoutes | RewriteRoutes
`
describe('typed-routes', () => {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment