Routing Utility

Copyexport { resolveRoutes } from './resolve-routes'
export type {
  RouteHas,
  Route,
  MiddlewareContext,
  MiddlewareResult,
  ResolveRoutesParams,
  ResolveRoutesResult,
  ResolveRoutesQuery,
  ResolveRoutesQueryValue,
  RouteInvocationTarget,
} from './types'
export type { I18nConfig, I18nDomain } from './i18n'
export {
  detectLocale,
  detectDomainLocale,
  normalizeLocalePath,
  getAcceptLanguageLocale,
  getCookieLocale,
} from './i18n'
export { responseToMiddlewareResult } from './middleware'

Copyexport type RouteHas =
  | {
      type: 'header' | 'cookie' | 'query'
      key: string
      value?: string
    }
  | {
      type: 'host'
      key?: undefined
      value: string
    }

Copyexport type ResolveRoutesParams = {
  url: URL
  buildId: string
  basePath: string
  requestBody: ReadableStream
  headers: Headers
  pathnames: string[]
  i18n?: {
    defaultLocale: string
    domains?: Array<{
      defaultLocale: string
      domain: string
      http?: true
      locales?: string[]
    }>
    localeDetection?: false
    locales: string[]
  }
  routes: {
    /**
     * When false (default), route matching is case-insensitive to mirror
     * Next.js default behavior. When true, matches are case-sensitive.
     */
    caseSensitive?: boolean
    beforeMiddleware: Array<Route>
    /**
     * Middleware matcher definitions used to decide whether middleware should
     * be invoked for the current request.
     */
    middlewareMatchers?: Array<Route>
    beforeFiles: Array<Route>
    afterFiles: Array<Route>
    dynamicRoutes: Array<Route>
    onMatch: Array<Route>
    fallback: Array<Route>
    shouldNormalizeNextData?: boolean
  }
  invokeMiddleware: (ctx: MiddlewareContext) => Promise<MiddlewareResult>
}

Copyexport type RouteInvocationTarget = {
  /**
   * Concrete pathname that should be invoked after routing resolution.
   */
  pathname: string
  /**
   * Concrete query that should be invoked after routing resolution.
   */
  query: ResolveRoutesQuery
}

Copyexport async function resolveRoutes(
  params: ResolveRoutesParams
): Promise<ResolveRoutesResult> {
  const {
    url: initialUrl,
    basePath,
    requestBody,
    headers: initialHeaders,
    pathnames,
    routes,
    invokeMiddleware,
    buildId,
    i18n,
  } = params
 
  const { shouldNormalizeNextData, caseSensitive = false } = routes
 
  let currentUrl = new URL(initialUrl.toString())
  let currentRequestHeaders = new Headers(initialHeaders)
  let currentResponseHeaders = new Headers()
  let currentStatus: number | undefined
  let pendingLocaleRedirect:
    | {
        url: URL
        status: number
      }
    | undefined
  let pendingBeforeMiddlewareStop:
    | {
        status: number | undefined
      }
    | undefined
  const initialOrigin = initialUrl.origin
 
  // Check if the original URL is a data URL and normalize if so
  let isDataUrl = false
  if (shouldNormalizeNextData) {
    const dataPrefix = `${basePath}/_next/data/${buildId}/`
    isDataUrl = initialUrl.pathname.startsWith(dataPrefix)
 
    if (isDataUrl) {
      currentUrl = normalizeNextDataUrl(currentUrl, basePath, buildId)
    }
  }
 

Copy// Handle i18n locale detection and redirects
if (i18n && !isDataUrl) {
  const pathname = currentUrl.pathname.startsWith(basePath)
    ? currentUrl.pathname.slice(basePath.length) || '/'
    : currentUrl.pathname
 
  // Skip locale handling for _next and api routes
  if (!pathname.startsWith('/_next/') && !pathname.startsWith('/api/')) {
    const hostname = currentUrl.hostname
    const cookieHeader = currentRequestHeaders.get('cookie') || undefined
    const acceptLanguageHeader =
      currentRequestHeaders.get('accept-language') || undefined
 
    // Detect locale from path first
    const pathLocaleResult = normalizeLocalePath(pathname, i18n.locales)
    const localeInPath = !!pathLocaleResult.detectedLocale
 
    // Detect domain locale
    const domainLocale = detectDomainLocale(i18n.domains, hostname)
    const defaultLocale = domainLocale?.defaultLocale || i18n.defaultLocale
 
    // Determine target locale if locale detection is enabled
    let targetLocale = pathLocaleResult.detectedLocale || defaultLocale
 
    // Match Next.js behavior: preferred-locale auto-detection redirects only
    // on index requests, not on arbitrary non-locale pathnames.
    const shouldDetectPreferredLocale =
      i18n.localeDetection !== false &&
      !localeInPath &&
      pathLocaleResult.pathname === '/'
 
    if (shouldDetectPreferredLocale) {
      const detectedResult = detectLocale({
        pathname,
        hostname,
        cookieHeader,
        acceptLanguageHeader,
        i18n,
      })
 
      targetLocale = detectedResult.locale
 
      // Check if we need to redirect based on domain or locale mismatch
      if (targetLocale !== defaultLocale) {
        const targetDomain = detectDomainLocale(
          i18n.domains,
          undefined,
          targetLocale
        )
 
        // Redirect to different domain if target locale has a different configured domain
        if (targetDomain && targetDomain.domain !== hostname) {
          const scheme = targetDomain.http ? 'http' : 'https'
          const localePrefix =
            targetLocale === targetDomain.defaultLocale
              ? ''
              : `/${targetLocale}`
          const redirectUrl = new URL(
            `${scheme}://${targetDomain.domain}${basePath}${localePrefix}${pathname}${currentUrl.search}`
          )
 
          pendingLocaleRedirect = {
            url: redirectUrl,
            status: 307,
          }
        }
 
        // If no dedicated domain for target locale, or we're already on the right domain,
        // redirect to add locale prefix on same domain
        if (
          !targetDomain ||
          (targetDomain && targetDomain.domain === hostname)
        ) {
          const redirectUrl = new URL(currentUrl.toString())
          redirectUrl.pathname = `${basePath}/${targetLocale}${pathname}`
 
          pendingLocaleRedirect = {
            url: redirectUrl,
            status: 307,
          }

Copy// Process beforeMiddleware routes
const beforeMiddlewareResult = processRoutes(
  routes.beforeMiddleware,
  currentUrl,
  currentRequestHeaders,
  currentResponseHeaders,
  initialOrigin,
  caseSensitive
)
 
if (beforeMiddlewareResult.status) {
  currentStatus = beforeMiddlewareResult.status
}
 
if (beforeMiddlewareResult.redirect) {
  return {
    redirect: beforeMiddlewareResult.redirect,
    resolvedHeaders: currentResponseHeaders,
    status: currentStatus,
  }
}
 
if (beforeMiddlewareResult.externalRewrite) {
  return {
    externalRewrite: beforeMiddlewareResult.externalRewrite,
    resolvedHeaders: currentResponseHeaders,
    status: currentStatus,
  }
}
 
if (beforeMiddlewareResult.stopped) {
  pendingBeforeMiddlewareStop = {
    status: currentStatus,
  }
}
 
currentUrl = beforeMiddlewareResult.url
 

Copylet middlewareInvocationUrl = currentUrl
 
// Denormalize before invoking middleware if this was originally a data URL
if (isDataUrl && shouldNormalizeNextData) {
  middlewareInvocationUrl = denormalizeNextDataUrl(
    currentUrl,
    basePath,
    buildId
  )
}
 
const shouldInvokeMiddleware = shouldInvokeMiddlewareForRequest(
  routes.middlewareMatchers,
  currentUrl,
  currentRequestHeaders,
  caseSensitive
)
 
if (shouldInvokeMiddleware) {
  // Invoke middleware
  const middlewareResult = await invokeMiddleware({
    url: middlewareInvocationUrl,
    headers: currentRequestHeaders,
    requestBody,
  })
 
  // Check if middleware sent the response body
  if (middlewareResult.bodySent) {
    return { middlewareResponded: true }
  }
 
  // Apply request headers from middleware
  if (middlewareResult.requestHeaders) {
    currentRequestHeaders = new Headers(middlewareResult.requestHeaders)
  }
 
  // Apply response headers from middleware
  if (middlewareResult.responseHeaders) {
    middlewareResult.responseHeaders.forEach((value, key) => {
      if (key.toLowerCase() === 'set-cookie') {
        currentResponseHeaders.append(key, value)
      } else {
        currentResponseHeaders.set(key, value)
      }
    })
  }
 
  // Handle middleware redirect
  if (middlewareResult.redirect) {
    if (!currentResponseHeaders.has('location')) {
      currentResponseHeaders.set(
        'Location',
        middlewareResult.redirect.url.toString()
      )
    }
    return {
      resolvedHeaders: currentResponseHeaders,
      status: middlewareResult.redirect.status,
    }
  }
 
  // Handle middleware rewrite
  if (middlewareResult.rewrite) {
    currentUrl = middlewareResult.rewrite
 
    // Check if it's an external rewrite
    if (currentUrl.origin !== initialOrigin) {
      return {
        externalRewrite: currentUrl,
        resolvedHeaders: currentResponseHeaders,
        status: currentStatus,
      }
    }
  }
}

Copyexport function replaceDestination(
  destination: string,
  regexMatches: RegExpMatchArray | null,
  hasCaptures: Record<string, string>
): string {
  const captureKeys = Object.keys(hasCaptures)
 
  if (regexMatches) {
    for (let index = 1; index < regexMatches.length; index++) {
      captureKeys.push(String(index))
    }
    if (regexMatches.groups) {
      captureKeys.push(...Object.keys(regexMatches.groups))
    }
  }
 
  if (captureKeys.length === 0) {
    return destination
  }
 
  const capturePattern = captureKeys
    .sort((first, second) => second.length - first.length)
    .map((key) => {
      const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
      return /^\d+$/.test(key) ? `${escapedKey}(?!\\d)` : escapedKey
    })
    .join('|')
 
  // Replace placeholders once. Captured paths can contain literal text such as
  // $2 or $d$segment that must not become another substitution.
  return destination.replace(
    new RegExp(`\\$(${capturePattern})`, 'g'),
    (placeholder, key: string) => {
      if (regexMatches) {
        const index = Number(key)
        if (
          Number.isInteger(index) &&
          index > 0 &&
          index < regexMatches.length &&
          String(index) === key
        ) {
          return regexMatches[index] ?? ''
        }
        if (regexMatches.groups && Object.hasOwn(regexMatches.groups, key)) {
          return regexMatches.groups[key] ?? ''
        }
      }
      if (Object.hasOwn(hasCaptures, key)) {
        return hasCaptures[key]
      }
      return placeholder
    }
  )
}

Copyexport function isExternalDestination(destination: string): boolean {
  return destination.startsWith('http://') || destination.startsWith('https://')
}

Copyexport function applyDestination(currentUrl: URL, destination: string): URL {
  if (isExternalDestination(destination)) {
    return new URL(destination)
  }
 
  // Create a new URL with the updated pathname
  const newUrl = new URL(currentUrl.toString())
 
  // Handle destinations with query strings
  const [pathname, search] = destination.split('?')
  newUrl.pathname = pathname
 
  if (search) {
    // Merge query parameters
    const newParams = new URLSearchParams(search)
    for (const [key, value] of newParams.entries()) {
      newUrl.searchParams.set(key, value)
    }
  }
 
  return newUrl
}

Copylet isDataUrl = false
if (shouldNormalizeNextData) {
  const dataPrefix = `${basePath}/_next/data/${buildId}/`
  isDataUrl = initialUrl.pathname.startsWith(dataPrefix)
 
  if (isDataUrl) {
    currentUrl = normalizeNextDataUrl(currentUrl, basePath, buildId)
  }
}

Copyexport function normalizeNextDataUrl(
  url: URL,
  basePath: string,
  buildId: string
): URL {
  const newUrl = new URL(url.toString())
  let pathname = newUrl.pathname
 
  // Pattern: ${basePath}/_next/data/${buildId}/${path}.json
  const dataPrefix = `${basePath}/_next/data/${buildId}/`
 
  if (pathname.startsWith(dataPrefix)) {
    // Remove the /_next/data/${buildId}/ part, keeping what comes after
    let pathAfterData = pathname.slice(dataPrefix.length)
 
    // Remove .json extension if present
    if (pathAfterData.endsWith('.json')) {
      pathAfterData = pathAfterData.slice(0, -5)
    }
 
    if (pathAfterData === 'index') {
      pathname = basePath || '/'
    } else {
      pathname = basePath ? `${basePath}/${pathAfterData}` : `/${pathAfterData}`
    }
    newUrl.pathname = pathname
  }
 
  return newUrl
}

Copy// Denormalize before invoking middleware if this was originally a data URL
if (isDataUrl && shouldNormalizeNextData) {
  middlewareInvocationUrl = denormalizeNextDataUrl(
    currentUrl,
    basePath,
    buildId
  )
}

Copyexport function denormalizeNextDataUrl(
  url: URL,
  basePath: string,
  buildId: string
): URL {
  const newUrl = new URL(url.toString())
  let pathname = newUrl.pathname
 
  // Only denormalize if it's not already a data URL
  const dataPrefix = `${basePath}/_next/data/${buildId}/`
  if (!pathname.startsWith(dataPrefix)) {
    // Remove basePath if present
    let pathWithoutBase = pathname
    if (basePath && pathname.startsWith(basePath)) {
      pathWithoutBase = pathname.slice(basePath.length)
    }
 
    if (pathWithoutBase === '' || pathWithoutBase === '/') {
      pathWithoutBase = '/index'
    }
 
    // Add the /_next/data/${buildId}/ prefix and .json extension
    pathname = `${basePath}/_next/data/${buildId}${pathWithoutBase}.json`
    newUrl.pathname = pathname
  }
 
  return newUrl

Copy// Normalize again after middleware if this was originally a data URL
if (isDataUrl && shouldNormalizeNextData) {
  currentUrl = normalizeNextDataUrl(currentUrl, basePath, buildId)
}

Copyconst output = await fsChecker.getItem(pathname)

Copyexport function adaptForPathParams(
  router: Pick<NextRouter, 'isReady' | 'pathname' | 'query' | 'asPath'>
): Params | null {
  if (!router.isReady || !router.query) {
    return null
  }
  const pathParams: Params = {}
  const routeRegex = getRouteRegex(router.pathname)
  const keys = Object.keys(routeRegex.groups)
  for (const key of keys) {
    pathParams[key] = router.query[key]!
  }
  return pathParams
}

Copyexport function resolveHref(
  router: NextRouter,
  href: Url,
  resolveAs: true
): [string, string] | [string]
export function resolveHref(
  router: NextRouter,
  href: Url,
  resolveAs?: false
): string
export function resolveHref(
  router: NextRouter,
  href: Url,
  resolveAs?: boolean
): [string, string] | [string] | string {

Copyexport function canonicalizeURLPart(part: string): string {
  try {
    return encodeURIComponent(decodeURIComponent(part))
  } catch {
    // `decodeURIComponent` throws on malformed sequences. Fall back to the
    // already-encoded form rather than failing the navigation.
    return part
  }
}