Routing with @next/routing

Core Idea

Use the @next/routing package's resolveRoutes() to reproduce Next.js's exact route matching behavior inside an adapter, using the routing data captured from onBuildComplete.

Key Concepts

• resolveRoutes(): takes { url, buildId, basePath, i18n, headers, requestBody, pathnames, routes, invokeMiddleware } and returns resolution results.
• Result fields: middlewareResponded (adapter shouldn't invoke entrypoint if true), externalRewrite (URL), redirect ({url, status}), resolvedPathname (route template, e.g. /blog/[slug]), resolvedQuery, invocationTarget (concrete pathname/query to invoke), resolvedHeaders, status, routeMatches.

Code Examples

import { resolveRoutes } from '@next/routing'

const pathnames = [
  ...outputs.pages,
  ...outputs.pagesApi,
  ...outputs.appPages,
  ...outputs.appRoutes,
  ...outputs.staticFiles,
].map((output) => output.pathname)

const result = await resolveRoutes({
  url: new URL(requestUrl),
  buildId,
  basePath: config.basePath || '',
  i18n: config.i18n,
  headers: new Headers(requestHeaders),
  requestBody,
  pathnames,
  routes: routing,
  invokeMiddleware: async (ctx) => {
    return {}
  },
})

if (result.resolvedPathname) {
  console.log('Resolved pathname:', result.resolvedPathname)
  console.log('Invocation target:', result.invocationTarget)
}

• O que demonstra: resolve uma request real contra os pathnames de build e o objeto routing do adapter, obtendo o alvo concreto a invocar.

Key Takeaways

1. resolvedPathname fica no template dinâmico (/blog/[slug]); invocationTarget.pathname é o path concreto (/blog/post-1).
2. invokeMiddleware é injetado pelo adapter, permitindo invocação de middleware específica da plataforma.
3. Evita reimplementar a lógica de matching de rotas do Next.js manualmente no adapter.

Connects To

• Output Types (ch441): outputs.pages/appPages/etc. alimentam a lista de pathnames.
• Routing Information (ch442): routing (de onBuildComplete) é passado diretamente como routes.