Redirects in Next.js

Overview

Method	Default status	Use it for
redirects() in next.config.js	308 (permanent: true) or 307	Static, known URL mappings
Middleware / Proxy with NextResponse.redirect()	307	Conditions at request time: cookies, geo, large redirect maps
redirect() in the App Router	307 (303 in Server Actions)	Redirects after logic in Server Components, Route Handlers, Server Actions
permanentRedirect()	308	A resource has moved for good, decided in server code
trailingSlash	308	Normalizing URLs with or without a trailing slash

Next.js prefers 307 and 308 over 302 and 301 because they guarantee that the request method is kept: a POST stays a POST. For search engines, 308 is equivalent to 301 and 307 to 302. Background is in 307 vs. 308.

redirects() in next.config.js

The redirects function in your config returns an array of rules. They are evaluated before the file system, so they also work for URLs that no longer have a page:

/** @type {import('next').NextConfig} */
const nextConfig = {
  async redirects() {
    return [
      // 308 Permanent Redirect
      {
        source: '/about-us',
        destination: '/about',
        permanent: true,
      },
      // Path parameter
      {
        source: '/blog/:slug',
        destination: '/news/:slug',
        permanent: true,
      },
      // Wildcard: matches /docs/a/b/c
      {
        source: '/docs/:path*',
        destination: 'https://docs.example.com/:path*',
        permanent: false,
      },
      // Explicit status code instead of permanent
      {
        source: '/old-shop',
        destination: '/shop',
        statusCode: 301,
      },
    ]
  },
}

module.exports = nextConfig

A few rules to remember:

• permanent: true sends 308, permanent: false sends 307. If you need a classic 301 for an old client, use statusCode instead of permanent, not both.
• Query strings are passed on to the destination automatically.
• With has and missing you can match on headers, cookies, query parameters or the host. That is how you redirect www to non-www inside Next.js:

{
  source: '/:path*',
  has: [{ type: 'host', value: 'www.example.com' }],
  destination: 'https://example.com/:path*',
  permanent: true,
}

If you host on Vercel, a domain redirect in the dashboard is simpler for this case, see Vercel and Netlify redirects. With next.config.ts the syntax is the same; you just export default nextConfig. Note that redirects() does not work with output: 'export', because a static export has no server that could send a status code.

Middleware: NextResponse.redirect()

Middleware runs before a route is rendered and can decide per request. Since Next.js 16 the file is called proxy.ts and the exported function proxy; in earlier versions it is middleware.ts with a function called middleware. The API is the same:

// proxy.ts (Next.js 16) or middleware.ts (Next.js 15 and older)
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function proxy(request: NextRequest) {
  if (!request.cookies.has('session')) {
    // 307 by default
    return NextResponse.redirect(new URL('/login', request.url))
  }

  if (request.nextUrl.pathname === '/old-pricing') {
    // explicit permanent redirect
    return NextResponse.redirect(new URL('/pricing', request.url), 308)
  }

  return NextResponse.next()
}

export const config = {
  matcher: ['/dashboard/:path*', '/old-pricing'],
}

NextResponse.redirect() needs an absolute URL, which is why the example builds it with new URL(path, request.url). Restrict the middleware with a matcher so it doesn't run on every image and static file.

Middleware is also the recommended place for large redirect lists (thousands of entries): load a map from a JSON file or an edge store, look up the pathname and redirect if there is a match. The config file is not meant for huge lists.

redirect() and permanentRedirect() in the App Router

In Server Components, Route Handlers and Server Actions you import the functions from next/navigation:

// app/products/[id]/page.tsx
import { redirect, permanentRedirect, notFound } from 'next/navigation'

export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  const product = await getProduct(id)

  if (!product) {
    notFound()
  }

  if (product.slug !== id) {
    // moved for good: 308
    permanentRedirect(`/products/${product.slug}`)
  }

  if (!product.published) {
    // temporary: 307
    redirect('/products')
  }

  return <h1>{product.name}</h1>
}

• redirect() sends 307; in a Server Action it sends 303 See Other, so the browser follows up with a GET.
• permanentRedirect() sends 308.
• Both throw internally, so you don't need return. Don't call them inside a try block, or your catch will swallow the redirect.
• If the response is already streaming, the status code can no longer change. Next.js then inserts a meta tag that redirects on the client. Crawlers treat that differently from a real HTTP redirect, so trigger redirects before any Suspense boundary starts streaming. Check the result with the redirect checker: it shows whether you get a 308 or a meta refresh.

In the Pages Router, the equivalent is returning { redirect: { destination: '/login', permanent: false } } from getServerSideProps or getStaticProps.

trailingSlash

By default Next.js redirects /about/ to /about with a 308. With trailingSlash: true it does the opposite:

module.exports = {
  trailingSlash: true, // /about -> /about/ (308)
}

Choose one form and keep internal links consistent with it; otherwise every internal link costs an extra hop. If a redirect in redirects() points to the "wrong" form, the trailing slash redirect is added on top and you get a redirect chain. With skipTrailingSlashRedirect: true you can switch the automatic redirect off and handle it yourself in middleware.

Redirects vs. rewrites

Both use the same source/destination syntax, but they do different things:

	Redirect	Rewrite
URL in the browser	Changes to the destination	Stays the same
HTTP response	3xx with Location header	200 with the content of the destination
Search engines	Index the destination	Index the original URL
Typical use	Moved content, domain changes	Proxying an API, clean URLs, multi-zone apps

async rewrites() {
  return [
    { source: '/api/:path*', destination: 'https://api.example.com/:path*' },
  ]
}

If a URL has really moved, use a redirect. A rewrite would leave the old URL indexed and serve duplicate content under two addresses.

Order of evaluation

Next.js processes a request in this order: headers, redirects, middleware/proxy, beforeFiles rewrites, file system routes, afterFiles rewrites, dynamic routes, fallback rewrites. A rule in redirects() therefore wins over a page with the same path and over your middleware.

Testing

next dev doesn't always behave like production, especially behind a CDN. After deploying, run the most important URLs through the redirect checker and look at the status code of every hop. For many URLs at once, use the bulk checker. To learn more about the status codes Next.js sends, see 301 vs. 302.