Version adapter routing for Pages API routes

docs/01-app/03-api-reference/07-adapters/03-api-reference.mdx

@@ -23,6 +23,7 @@ Called after the build process completes with detailed information about routes
 **Parameters:**
 
 - `context.routing`: Object containing Next.js routing phases and metadata
+  - `routing.version`: Version of the routing contract. Version `2` keeps dynamic Pages API routes in the canonical `/api` namespace. Manifests without a version use the legacy version `1` semantics.
   - `routing.beforeMiddleware`: Routes executed before middleware (includes header and redirect handling)
   - `routing.middlewareMatchers`: Middleware matcher definitions for this build, used to decide whether middleware should be invoked for a given request
   - `routing.beforeFiles`: Rewrite routes checked before filesystem route matching

packages/next/src/build/adapter/build-complete.ts

@@ -9,6 +9,7 @@ import { interopDefault } from '../../lib/interop-default'
 import type { RouteHas } from '../../lib/load-custom-routes'
 import { recursiveReadDir } from '../../lib/recursive-readdir'
 import { isDynamicRoute } from '../../shared/lib/router/utils'
+import { isAPIRoute } from '../../lib/is-api-route'
 import type { Revalidate } from '../../server/lib/cache-control'
 import type { NextConfigComplete } from '../../server/config-shared'
 import {
@@ -520,6 +521,11 @@ export interface NextAdapter {
   ) => Promise<NextConfigComplete> | NextConfigComplete
   onBuildComplete?: (ctx: {
     routing: {
+      /**
+       * Version of the routing manifest contract. Unversioned manifests use
+       * the legacy version 1 semantics.
+       */
+      version: 2
       beforeMiddleware: Array<Route>
       /**
        * middlewareMatchers are the middleware matcher definitions emitted by
@@ -2125,7 +2131,7 @@ export async function handleBuildComplete({
         route.page
       )
 
-      const shouldLocalize = Boolean(config.i18n)
+      const shouldLocalize = Boolean(config.i18n && !isAPIRoute(route.page))
 
       const routeRegex = getNamedRouteRegex(route.page, {
         prefixRouteKeys: true,
@@ -2423,6 +2429,7 @@ export async function handleBuildComplete({
 
       await adapterMod.onBuildComplete({
         routing: {
+          version: 2,
           beforeMiddleware: [...headers, ...redirects],
           middlewareMatchers:
             outputs.middleware?.config.matchers?.map((matcher) => ({

test/production/adapter-config-i18n/adapter-config-i18n.test.ts

@@ -6,11 +6,7 @@ describe('adapter config with i18n routes', () => {
     files: __dirname,
   })
 
-  // Dynamic Pages API routes are localized like any other dynamic route. The
-  // Vercel adapter's i18n rules prefix the locale onto `/api/...` too, so the
-  // matcher has to expect it — if the two disagree the matcher is unreachable
-  // and requests fall through to `/{locale}/404`. See vercel/next.js#96935.
-  it('localizes dynamic Pages API routes', async () => {
+  it('keeps dynamic Pages API routes in the canonical namespace', async () => {
     const { outputs, routing }: Parameters<NextAdapter['onBuildComplete']>[0] =
       await next.readJSON('build-complete.json')
 
@@ -24,11 +20,12 @@ describe('adapter config with i18n routes', () => {
       (route) => route.source === '/blog/[slug]'
     )
 
+    expect(routing.version).toBe(2)
     expect(apiOutput).toBeDefined()
     expect(apiRoute).toBeDefined()
-    expect(apiRoute?.sourceRegex).toContain('nextLocale')
+    expect(apiRoute?.sourceRegex).not.toContain('nextLocale')
     expect(apiRoute?.destination).toBe(
-      '/$nextLocale/api/proxy/[[...slug]]?nxtPslug=$nxtPslug'
+      '/api/proxy/[[...slug]]?nxtPslug=$nxtPslug'
     )
 
     expect(pageRoute).toBeDefined()

test/production/adapter-config/adapter-config-export.test.ts

@@ -83,6 +83,7 @@ describe('adapter-config export', () => {
     }
 
     expect(routing).toEqual({
+      version: 2,
       beforeMiddleware: expect.toBeArray(),
       middlewareMatchers: expect.toBeArray(),
       beforeFiles: expect.toBeArray(),

test/production/adapter-config/adapter-config.test.ts

@@ -451,6 +451,7 @@ describe('adapter-config', () => {
     }
 
     expect(routing).toEqual({
+      version: 2,
       beforeMiddleware: expect.toBeArray(),
       middlewareMatchers: expect.toBeArray(),
       beforeFiles: expect.toBeArray(),