Refactor to share handler logic in route-module (#79106)

This pulls the logic added in `templates/pages-api` that is needed to
support the `handler` interface into the `route-module` interface so
that it can shared with the other templates as the `handler` interface
is added for them as well.

Validated against deploy tests here:
https://github.com/vercel/vercel/actions/runs/14982451661/job/42089544277?pr=13326

Author: ijjk

packages/next/src/build/templates/app-page.ts

@@ -48,4 +48,5 @@ export const routeModule = new AppPageRouteModule({
   userland: {
     loaderTree: tree,
   },
+  distDir: process.env.__NEXT_RELATIVE_DIST_DIR || '',
 })

packages/next/src/build/templates/app-route.ts

@@ -24,6 +24,7 @@ const routeModule = new AppRouteRouteModule({
     filename: 'VAR_DEFINITION_FILENAME',
     bundlePath: 'VAR_DEFINITION_BUNDLE_PATH',
   },
+  distDir: process.env.__NEXT_RELATIVE_DIST_DIR || '',
   resolvedPagePath: 'VAR_RESOLVED_PAGE_PATH',
   nextConfigOutput,
   userland,

packages/next/src/build/templates/pages-api.ts

@@ -1,8 +1,5 @@
 import type { NextApiResponse } from '../../types'
 import type { IncomingMessage, ServerResponse } from 'node:http'
-import type { PrerenderManifest } from '..'
-import type { DevRoutesManifest } from '../../server/lib/router-utils/setup-dev-bundler'
-import type { InstrumentationOnRequestError } from '../../server/instrumentation/types'
 
 import { sendError } from '../../server/api-utils'
 import { RouteKind } from '../../server/route-kind'
@@ -15,26 +12,6 @@ import { hoist } from './helpers'
 import * as userland from 'VAR_USERLAND'
 import { getTracer, SpanKind } from '../../server/lib/trace/tracer'
 import { BaseServerSpan } from '../../server/lib/trace/constants'
-import {
-  ensureInstrumentationRegistered,
-  instrumentationOnRequestError,
-} from '../../server/lib/router-utils/instrumentation-globals.external'
-import { getUtils } from '../../server/server-utils'
-import { PRERENDER_MANIFEST, ROUTES_MANIFEST } from '../../api/constants'
-import { isDynamicRoute } from '../../shared/lib/router/utils'
-import {
-  RouterServerContextSymbol,
-  routerServerGlobal,
-} from '../../server/lib/router-utils/router-server-context'
-import { removePathPrefix } from '../../shared/lib/router/utils/remove-path-prefix'
-import {
-  normalizeLocalePath,
-  type PathLocale,
-} from '../../shared/lib/i18n/normalize-locale-path'
-import { loadManifestFromRelativePath } from '../../server/load-manifest.external'
-import { getHostname } from '../../shared/lib/get-hostname'
-import { detectDomainLocale } from '../../shared/lib/i18n/detect-domain-locale'
-import { parseReqUrl } from '../../lib/url'
 
 // Re-export the handler (should be the default export).
 export default hoist(userland, 'default')
@@ -53,6 +30,7 @@ const routeModule = new PagesAPIRouteModule({
     filename: '',
   },
   userland,
+  distDir: process.env.__NEXT_RELATIVE_DIST_DIR || '',
 })
 
 export async function handler(
@@ -62,23 +40,6 @@ export async function handler(
     waitUntil?: (prom: Promise<void>) => void
   }
 ): Promise<void> {
-  const projectDir =
-    routerServerGlobal[RouterServerContextSymbol]?.dir || process.cwd()
-  const distDir = process.env.__NEXT_RELATIVE_DIST_DIR || ''
-  const isDev = process.env.NODE_ENV === 'development'
-
-  const [routesManifest, prerenderManifest] = await Promise.all([
-    loadManifestFromRelativePath<DevRoutesManifest>(
-      projectDir,
-      distDir,
-      ROUTES_MANIFEST
-    ),
-    loadManifestFromRelativePath<PrerenderManifest>(
-      projectDir,
-      distDir,
-      PRERENDER_MANIFEST
-    ),
-  ])
   let srcPage = 'VAR_DEFINITION_PAGE'
 
   // turbopack doesn't normalize `/index` in the page name
@@ -87,95 +48,16 @@ export async function handler(
     srcPage = srcPage.replace(/\/index$/, '')
   }
 
-  // We need to parse dynamic route params
-  // and do URL normalization here.
-  // TODO: move this into server-utils for re-use
-  const { basePath, i18n, rewrites } = routesManifest
-
-  if (basePath) {
-    req.url = removePathPrefix(req.url || '/', basePath)
-  }
-
-  let localeResult: PathLocale | undefined
-
-  if (i18n) {
-    const urlParts = (req.url || '/').split('?')
-    localeResult = normalizeLocalePath(urlParts[0] || '/', i18n.locales)
-
-    if (localeResult.detectedLocale) {
-      req.url = `${localeResult.pathname}${
-        urlParts[1] ? `?${urlParts[1]}` : ''
-      }`
-    }
-  }
-
-  const parsedUrl = parseReqUrl(req.url || '/')
+  const prepareResult = await routeModule.prepare(req, srcPage)
 
-  if (!parsedUrl) {
+  if (!prepareResult) {
     res.statusCode = 400
     res.end('Bad Request')
     ctx.waitUntil?.(Promise.resolve())
     return
   }
 
-  const pageIsDynamic = isDynamicRoute(srcPage)
-
-  const serverUtils = getUtils({
-    page: srcPage,
-    i18n,
-    basePath,
-    rewrites,
-    pageIsDynamic,
-    trailingSlash: process.env.__NEXT_TRAILING_SLASH as any as boolean,
-    caseSensitive: Boolean(routesManifest.caseSensitive),
-  })
-
-  const domainLocale = detectDomainLocale(
-    i18n?.domains,
-    getHostname(parsedUrl, req.headers),
-    localeResult?.detectedLocale
-  )
-
-  const defaultLocale = domainLocale?.defaultLocale || i18n?.defaultLocale
-
-  // Ensure parsedUrl.pathname includes locale before processing
-  // rewrites or they won't match correctly.
-  if (defaultLocale && !localeResult?.detectedLocale) {
-    parsedUrl.pathname = `/${defaultLocale}${parsedUrl.pathname}`
-  }
-
-  const rewriteParamKeys = Object.keys(
-    serverUtils.handleRewrites(req, parsedUrl)
-  )
-  serverUtils.normalizeCdnUrl(req, [
-    ...rewriteParamKeys,
-    ...Object.keys(serverUtils.defaultRouteRegex?.groups || {}),
-  ])
-
-  const params: Record<string, undefined | string | string[]> =
-    serverUtils.dynamicRouteMatcher
-      ? serverUtils.dynamicRouteMatcher(
-          localeResult?.pathname || parsedUrl.pathname || ''
-        ) || {}
-      : {}
-
-  const query = {
-    ...parsedUrl.query,
-    ...params,
-  }
-  serverUtils.normalizeQueryParams(query)
-
-  if (pageIsDynamic) {
-    const result = serverUtils.normalizeDynamicRouteParams(query, true)
-
-    if (result.hasValidParams) {
-      Object.assign(query, result.params)
-    }
-  }
-
-  // ensure instrumentation is registered and pass
-  // onRequestError below
-  await ensureInstrumentationRegistered(projectDir, distDir)
+  const { query, params, prerenderManifest } = prepareResult
 
   try {
     const method = req.method || 'GET'
@@ -197,11 +79,10 @@ export async function handler(
           // doesn't need to load
           previewProps: prerenderManifest.preview,
           propagateError: false,
-          dev: isDev,
+          dev: routeModule.isDev,
           page: 'VAR_DEFINITION_PAGE',
 
-          onError: (...args: Parameters<InstrumentationOnRequestError>) =>
-            instrumentationOnRequestError(projectDir, distDir, ...args),
+          onError: routeModule.instrumentationOnRequestError.bind(routeModule),
         })
         .finally(() => {
           if (!span) return
@@ -266,7 +147,7 @@ export async function handler(
     }
   } catch (err) {
     // we re-throw in dev to show the error overlay
-    if (isDev) {
+    if (routeModule.isDev) {
       throw err
     }
     // this is technically an invariant as error handling

packages/next/src/build/templates/pages.ts

@@ -51,6 +51,7 @@ export const routeModule = new PagesRouteModule({
     bundlePath: '',
     filename: '',
   },
+  distDir: process.env.__NEXT_RELATIVE_DIST_DIR || '',
   components: {
     // default export might not exist when optimized for data only
     App: app.default,

packages/next/src/build/webpack/loaders/next-edge-ssr-loader/index.ts

@@ -55,6 +55,8 @@ function getRouteModuleOptions(page: string) {
       bundlePath: '',
       filename: '',
     },
+    // edge runtime doesn't read from distDir
+    distDir: '',
   }
 
   return options

packages/next/src/server/base-server.ts

@@ -84,7 +84,7 @@ import RenderResult from './render-result'
 import { removeTrailingSlash } from '../shared/lib/router/utils/remove-trailing-slash'
 import { denormalizePagePath } from '../shared/lib/page-path/denormalize-page-path'
 import * as Log from '../build/output/log'
-import { getPreviouslyRevalidatedTags, getUtils } from './server-utils'
+import { getPreviouslyRevalidatedTags, getServerUtils } from './server-utils'
 import isError, { getProperError } from '../lib/is-error'
 import {
   addRequestMeta,
@@ -1191,7 +1191,7 @@ export default abstract class Server<
             matchedPath = localeAnalysisResult.pathname
           }
 
-          const utils = getUtils({
+          const utils = getServerUtils({
             pageIsDynamic,
             page: srcPathname,
             i18n: this.nextConfig.i18n,

packages/next/src/server/route-modules/app-route/module.ts

@@ -215,10 +215,11 @@ export class AppRouteRouteModule extends RouteModule<
   constructor({
     userland,
     definition,
+    distDir,
     resolvedPagePath,
     nextConfigOutput,
   }: AppRouteRouteModuleOptions) {
-    super({ userland, definition })
+    super({ userland, definition, distDir })
 
     this.resolvedPagePath = resolvedPagePath
     this.nextConfigOutput = nextConfigOutput

packages/next/src/server/route-modules/pages/builtin/_error.tsx

@@ -15,6 +15,7 @@ export const routeModule = new PagesRouteModule({
     filename: '',
     bundlePath: '',
   },
+  distDir: process.env.__NEXT_RELATIVE_DIST_DIR || '',
   components: {
     App,
     Document,