Routing with @next/routing

Core Idea

@next/routing's resolveRoutes() reproduces Next.js's own route-matching logic outside the framework, letting an adapter resolve a request against the routing/output data from onBuildComplete.

Key Concepts

• resolveRoutes(options): async function taking url, buildId, basePath, i18n, headers, requestBody, pathnames, routes, invokeMiddleware and returning a resolution result.
• invokeMiddleware: callback the adapter implements to actually run middleware for the platform; resolveRoutes calls it as part of resolution.
• middlewareResponded: result field, true when middleware already sent a response (adapter must not invoke an entrypoint).
• resolvedPathname: the matched route template (e.g. /blog/[slug] for dynamic routes), distinct from invocationTarget.
• invocationTarget: concrete pathname + query to actually invoke for the matched route.

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, // ReadableStream
  pathnames,
  routes: routing,
  invokeMiddleware: async (ctx) => {
    // platform-specific middleware invocation
    return {}
  },
})

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

• O que demonstra: montagem da lista de pathnames a partir dos outputs e chamada de resolveRoutes com o objeto routing vindo de onBuildComplete.

Reference Tables

resolveRoutes() result field	Meaning
middlewareResponded	true if middleware already sent the response
externalRewrite	URL when routing resolved to an external rewrite destination
redirect	{ url, status } when a redirect should occur
resolvedPathname	Route template selected (dynamic segments kept, e.g. /blog/[slug])
resolvedQuery	Final query after rewrites/middleware
invocationTarget	Concrete pathname + query to invoke
resolvedHeaders	Headers added/modified during routing
status	HTTP status set by routing
routeMatches	Named matches extracted from dynamic segments

Key Takeaways

1. resolveRoutes is the recommended way to match requests exactly as Next.js would, instead of hand-rolling regex matching from routing.
2. Example: /blog/post-1?draft=1 resolves resolvedPathname to /blog/[slug] while invocationTarget.pathname is /blog/post-1.
3. Middleware invocation is delegated back to the adapter via invokeMiddleware, keeping platform specifics out of @next/routing.

Connects To

• ch280 routing-information: source of the routing object passed as routes.
• ch279 output-types: source of outputs.* used to build pathnames.