mirror of https://github.com/hanzoai/next.js.git synced 2026-10-30 14:46:38 +00:00

Files

T

JJ KasperandGitHub d5e886399c Expose resolved invocation targets in next-routing (#91242 )

### What?

This PR extends `@next/routing` so `resolveRoutes()` returns the
concrete route resolution data callers need after rewrites and dynamic
matches:

- rename `matchedPathname` to `resolvedPathname`
- add `resolvedQuery`
- add `invocationTarget` for the concrete pathname/query that should be
invoked
- export the new query/invocation target types from the package
entrypoint

It also removes the leftover `query` alias so the result shape
consistently uses `resolvedQuery`.

### Why?

`matchedPathname` only described part of the result, and it was
ambiguous for dynamic routes because the resolved route template and the
concrete invocation target are not always the same thing.

For example, a dynamic route can resolve to `/blog/[slug]` while the
actual invocation target is `/blog/post-1`, and rewrites can merge query
params that callers need to preserve. Exposing these values directly
makes the package easier to consume from adapters without each caller
reconstructing them manually.

### How?

- thread resolved query construction through the route resolution paths
- build `invocationTarget` alongside `resolvedPathname` wherever
rewrites, static matches, and dynamic matches resolve successfully
- preserve merged rewrite query params in `resolvedQuery`
- update the public types, README example, and existing tests to use
`resolvedPathname`
- add coverage for resolved query + invocation target behavior on
rewrite and dynamic route matches

Verified with:
- `pnpm --filter @next/routing test -- --runInBand`
- `pnpm --filter @next/routing build`

2026-03-13 09:39:29 -07:00

2.4 KiB

Raw Permalink Blame History

@next/routing

Shared route resolving package for Next.js.

NOTE: This package is experimental and will become stable along with adapters API

Overview

This package provides a comprehensive route resolution system that handles rewrites, redirects, middleware invocation, and dynamic route matching with support for conditional routing based on headers, cookies, queries, and host.

Installation

npm install @next/routing

Usage

import { resolveRoutes } from '@next/routing'

const result = await resolveRoutes({
  url: new URL('https://example.com/api/users'),
  basePath: '',
  requestBody: readableStream,
  headers: new Headers(),
  pathnames: ['/api/users', '/api/posts'],
  routes: {
    beforeMiddleware: [],
    beforeFiles: [],
    afterFiles: [],
    dynamicRoutes: [],
    onMatch: [],
    fallback: [],
  },
  invokeMiddleware: async (ctx) => {
    // Your middleware logic
    return {}
  },
})

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

Route Resolution Flow

beforeMiddleware routes - Applied before middleware execution
invokeMiddleware - Custom middleware logic
beforeFiles routes - Applied before checking filesystem
Static pathname matching - Check against provided pathnames
afterFiles routes - Applied after filesystem checks
dynamicRoutes - Dynamic route matching with parameter extraction
fallback routes - Final fallback routes

Route Configuration

Each route can have:

sourceRegex - Regular expression to match against pathname
destination - Destination path with support for replacements ($1, $name)
headers - Headers to apply on match
has - Conditions that must match
missing - Conditions that must not match
status - HTTP status code (3xx for redirects)

Redirects

When a route has:

A redirect status code (300-399)
Headers containing Location or Refresh

The routing will end immediately and return a redirect result with the destination URL and status code.

Has/Missing Conditions

Conditions support:

header - Match HTTP headers
cookie - Match cookies
query - Match query parameters
host - Match hostname

Values can be:

undefined - Match if key exists
String - Direct string match
Regex string - Match against regex pattern

2.4 KiB Raw Permalink Blame History