Redirects and Rewrites

Marketing renames /pricing to /plans. Two questions decide everything: does the client end up at the new URL, and which status code tells it how to behave? A redirect answers both — the server returns a status plus Location, and the browser re-issues the request there.

Next.js uses 307 (temporary) and 308 (permanent) rather than the classic 301/302, and the reason is a real browser behavior: many clients rewrite a redirected POST into a bodyless GET when they see 301 or 302. A form submitted to /checkout that bounces through a 302 reaches /cart as a GET with no payload, and the order vanishes without an error. 307 and 308 preserve the method and the body — that is why the docs call the choice out explicitly.

That last column is the trap: browsers and crawlers remember a 308 until the user clears data, so rolling one back is painful. Ship a 308 only for renames that will never come back.

Where you declare the redirect determines how it reads:

// next.config.js — declarative, evaluated before your middleware
module.exports = {
  redirects() {
    return [
      { source: '/pricing', destination: '/plans', permanent: true },  // → 308
      { source: '/promo',   destination: '/',      permanent: false }, // → 307
    ]
  },
}

permanent: true maps to 308 and false to 307; for legacy clients you may set statusCode instead — never both (Next.js even appends a Refresh header alongside 308 responses so old IE11-era clients follow it). Query strings survive automatically: a request for /old-blog/post-1?hello=world matching source: '/old-blog/:path*' arrives at /blog/post-1?hello=world. Both patterns must start with / and are anchored, so /about does not match /blog/about.

Per-request decisions belong in middleware, where you pick the code on the spot:

import { NextResponse, type NextRequest } from 'next/server'

export default function middleware(request: NextRequest) {
  const country = request.headers.get('x-vercel-ip-country')
  if (country === 'DE') {
    return NextResponse.redirect(new URL('/de/pricing', request.url))      // 307
  }
  return NextResponse.next()
}

Inside Server Components and route handlers the API is redirect() from next/navigation. It throws a special NEXT_REDIRECT error that the framework catches while unwinding the render — so a try/catch that swallows the exception swallows the redirect with it. permanentRedirect() uses the same mechanism and produces a 308.

Two failure modes are worth recognizing on sight. First, infinite loops: a source that resolves to its own destination — usually from a missing leading slash on a path parameter (/:path* versus the literal :path), a trailing-slash disagreement, or a config redirect fighting a middleware redirect — makes the browser report a "too many redirects" error. Second, method loss during migration: if you must redirect an API POST, verify the status is 307/308 with a curl replay, not a browser click, because a browser will happily mask a broken GET conversion.

Remember the layering from Writing Middleware: config redirects are applied before middleware runs, so a permanent rule declared there needs no matcher, no invocation, and no cold start — it simply answers. Save your function for conditions that only exist at request time. When the URL must stay the same while the serving route changes, you want a rewrite instead — the next chapter.

A rewrite answers the other question: which route should serve this request while the browser keeps displaying the original URL. No second round trip, no Location header, no SEO signal — the outside world cannot tell the difference. That makes rewrites the tool for masking internal structure: serving /docs/* from a legacy CMS, exposing /api/report through an internal handler, or parking an unmigrated section at an old domain.

Two declaration sites, very different costs. Rules in next.config.js are declarative — Next.js evaluates them in the router without invoking your JavaScript on every request, which is exactly why the static cases belong there. A rewrite returned from middleware runs your function for each matched request, which is what you want only when the destination depends on session state, geography, or an experiment bucket.

// next.config.js
module.exports = {
  rewrites() {
    return {
      beforeFiles: [
        { source: '/override', destination: '/somewhere-else',
          has: [{ type: 'query', key: 'overrideMe' }] },
      ],
      afterFiles: [
        { source: '/non-existent', destination: '/somewhere-else' },
      ],
      fallback: [
        { source: '/:path*', destination: 'https://my-old-site.com/:path*' },
      ],
    }
  },
}

The three phases sit at fixed points in the routing chain, and the order is the interview answer:

Full chain: headers → redirects → middleware/proxy → beforeFiles → filesystem → afterFiles → dynamic routes → fallback → 404. Entries inside each phase are checked in the order you write them, and the first one that applies wins.

Parameter passing has a rule people get wrong: any matched parameter not used in the destination is appended to the query string automatically. source: '/old-about/:path*' with destination: '/about' yields /about?path=about-us. Use the parameter in the destination ('/docs/:path*' → '/:path*') and the automatic passing switches off — add it manually ('/:first?second=:second') if you still need it. External destinations (https://old-site/:path*) are allowed and are how a fallback proxy migrates page by page; basePath: false applies only to external entries.

One App Router subtlety separates a correct rewrite from a subtly broken one: returning NextResponse.rewrite() propagates the internal RSC rewrite headers upstream automatically, so the RSC payload request and the document request stay in sync. If you hand-roll the equivalent with fetch() and return the bytes yourself, those headers are missing and client-side navigation misbehaves unless you forward them (or enable skipProxyUrlNormalize so your code sees the original URL shape). Reach for the framework primitive first.

The sharp edges: rewriting to a route that returns 404 keeps the original URL on screen — a soft-404 that looks fine to users and confusing to crawlers; rewriting to an external host leaks your internal naming if the destination renders; and a rewrite plus a redirect on the same path can loop. Runtime choices — which environment executes that rewrite — is Edge vs Node Runtimes, and the layer-selection logic is next.

Every URL change request — "move this page", "hide this path", "send German users there" — reduces to two axes: does the URL the user sees change, and is the decision static or request-dependent? Fill in both and the layer picks itself.

Two columns deserve the emphasis. "Does the URL change?" separates redirect from rewrite: a redirect hands the browser a new location and the old URL stops existing (308 aside, permanently); a rewrite serves different content under the same URL, which is what you want when the path is part of your public contract — a partner integration hitting /api/export must not break because you reorganized internals. And "Per-request cost" separates config from middleware: declarative rules run in the router without invoking your code, so the exhaustive redirect table for a thousand legacy paths belongs in next.config.js, not in a matcher-scoped function that ships, parses, and executes for every hit.

Work a concrete case interviewers like: move /blog to /news and keep old post URLs alive. The answer in layers: a config redirects() entry { source: '/blog/:slug*', destination: '/news/:slug*', permanent: true } for the renames (308, method-preserving, zero runtime cost); query parameters pass through automatically; then verify with curl -I that the status is 308 and not a 302 your tooling added; and only if the mapping needs per-request data — say, serving deprecated posts from an archive only for logged-in subscribers — does it move into middleware with a matcher scoped to /blog/:path*. Anything needing data you don't have until the page renders (a user with no saved addresses) uses redirect() in the Server Component, and you accept that it unwinds the render via NEXT_REDIRECT.

Common failure signatures, so you can diagnose fast:

• "Too many redirects" — a source resolving to itself, usually a missing leading slash before :path, a trailing-slash mismatch (check skipTrailingSlashRedirect), or config and middleware each redirecting the other's destination.
• POST arrives as GET with no body — a 301/302 entered the chain from a proxy or legacy rule; Next's own rules are 307/308 for exactly this reason.
• Soft 404 — a rewrite landing on a route that renders not-found while the original URL stays; crawlers index an empty page.
• Redirect works locally, 404s in production — config redirects() are read at build time in some deployments; they must be present in the build that ships.

Performance framing closes the loop with Writing Middleware: every request your matcher lets through pays your function's latency, while every rule you move to next.config.js pays nothing. Push decisions up the chain until they genuinely require the request.

The remaining question is where that code executes when it does require the request — the subject of Edge vs Node Runtimes.