Redirects

Sending a visitor to another address

A redirect sends a visitor who asks for one address to another one. The tea shop needs a few. Its old menu page moved to /teas, and the tea it once called Peppermint is now Mint tea, at /teas/mint. People still have the old addresses in bookmarks, search results and links on other sites, and those should keep working.

Next.js gives you two functions for it, redirect() and permanentRedirect(), from next/navigation. Call one while a page renders, and the page stops there and the visitor goes to the address you passed. Here is the shop with both. Like every example in this lesson, it's a real Next.js 16.4.3 project. It was built with next build and run with next start, and what it sent back was recorded.

1import { redirect } from "next/navigation";2 3export default function MenuPage() {4  redirect("/teas");5}

<!DOCTYPE html>
<html id="__next_error__">
  <head>
    <link rel="preload" as="script" fetchpriority="low" href="/_next/static/chunks/1x6obpmlu1_c2.js">
    <script src="/_next/static/chunks/06bs-nf19b2js.js" async=""></script>
    <script src="/_next/static/chunks/2ki52vdnbo2ft.js" async=""></script>
    <script src="/_next/static/chunks/3l_qmp-61z4yc.js" async=""></script>
    <script src="/_next/static/chunks/turbopack-3-ry682tkyiqk.js" async=""></script>
    <script src="/_next/static/chunks/3oh00mkbkq8u6.js" async=""></script>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
  </head>
  <body>
    <script id="_R_">…</script>
    <script src="/_next/static/chunks/1x6obpmlu1_c2.js" async=""></script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
  </body>
</html>

In app/menu/page.tsx, the file shown first, line 1 imports redirect, and line 4 calls it with the new address, "/teas". The page returns nothing, and it doesn't need to: redirect() never returns, so no line after it would run. Click app/teas/peppermint/page.tsx: the same shape, with permanentRedirect("/teas/mint") on line 4.

The Network tab is open on /menu. A browser and a server talk in requests and responses, and every response starts with a status code: a three-digit number that says how the request went. 200 means "here is the page". /menu answered 307 instead, with a header named location whose value is /teas. (A header is a name and a value that come before the response's body.) Pick /teas/peppermint above the page: 308, with location: /teas/mint. Neither answer holds a page. Pick /teas: 200, and the page.

Now open the Steps tab. The recorder also opened /menu in real Chrome, and that one step made two document requests, which means whole HTML pages: GET /menu answered 307, and GET /teas answered 200. The address bar ends at /teas. The visitor never sees anything at /menu; the browser followed the location header on its own.

redirect() and permanentRedirect() in a page

Open the Terminal tab of the example above. The build lists ○ /menu and ○ /teas/peppermint. ○ means prerendered as static content: Next.js ran both pages during next build. Each one called its function, and Next.js stored the redirect itself, the status and the address, as that page's answer. Back in the Network tab, /menu carries the same x-nextjs-cache: HIT and Cache-Control: s-maxage=31536000 as /teas. It's sent like any static page, without running MenuPage again.

A real page usually redirects only sometimes, after it has read something. The tea shop's account page shows a visitor's orders, and sends a visitor who isn't signed in to /sign-in. Who is signed in comes from a cookie named session. The browser keeps it and sends it with each request, so the server only learns the visitor's current session when a request comes in:

1import { Suspense } from "react";2import { cookies } from "next/headers";3import { redirect } from "next/navigation";4 5async function Orders() {6  const name = (await cookies()).get("session")?.value;7  if (!name) {8    redirect("/sign-in");9  }10  return <p>Signed in as {name}. You have 2 orders.</p>;11}12 13export default function AccountPage() {14  return (15    <main>16      <h1>Your account</h1>17      <Suspense fallback={<p>Checking who you are…</p>}>18        <Orders />19      </Suspense>20    </main>21  );22}

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="preload" as="script" fetchpriority="low" href="/_next/static/chunks/1x6obpmlu1_c2.js">
    <script src="/_next/static/chunks/06bs-nf19b2js.js" async=""></script>
    <script src="/_next/static/chunks/2ki52vdnbo2ft.js" async=""></script>
    <script src="/_next/static/chunks/3l_qmp-61z4yc.js" async=""></script>
    <script src="/_next/static/chunks/turbopack-3-ry682tkyiqk.js" async=""></script>
    <script src="/_next/static/chunks/3oh00mkbkq8u6.js" async=""></script>
    <title>Tea shop</title>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
  </head>
  <body>
    <div hidden="">
      <!--$-->
      <!--/$-->
    </div>
    <nav><a href="/">Home</a> <a href="/teas">Teas</a></nav>
    <!--&-->
    <!--&-->
    <main>
      <h1>Your account</h1>
      <!--$?-->
      <template id="B:0"></template>
      <p>Checking who you are…</p>
      <!--/$-->
    </main>
    <!--$-->
    <!--/$-->
    <!--/&-->
    <!--/&-->
    <script>…</script>
    <script id="_R_">…</script>
    <script src="/_next/static/chunks/1x6obpmlu1_c2.js" async=""></script>
    <script>…</script>
    <script>…</script>
    <meta id="__next-page-redirect" http-equiv="refresh" content="1;url=/sign-in">
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
    <script>…</script>
    <script>…</script>
  </body>
</html>

Line 6 reads the cookie with cookies(). Lines 7 to 9 call redirect("/sign-in") when there is none. Otherwise line 10 shows the orders. Orders waits for request-time data, so with Cache Components on, as in every project in this course, it sits inside a Suspense on lines 17 to 19, with Checking who you are… as its fallback. (Loading UI explains why the build insists on one.)

Now read the Network tab. Without the cookie, /account answered 200, not 307. Here's why. The page's static shell, the part made during the build with the heading and the fallback, left the server first, and the status code goes out with the first part of a response. By the time Orders called redirect(), the 200 was already sent. So this answer isn't an HTTP redirect: no 3xx status, and no location header. Next.js put the redirect in the rest of the response instead: near the end of the HTML is <meta id="__next-page-redirect" http-equiv="refresh" content="1;url=/sign-in">, a tag that tells a browser to load /sign-in after 1 second, even without the page's JavaScript.

The Steps tab shows where Chrome ended up: GET /account answered 200, then Chrome loaded GET /sign-in as a new page, and the address bar ends at /sign-in. The visitor got there. But a search engine or a link checker that reads only the status sees a working page at /account. Pick /account, signed in as Asha: with the cookie session=Asha, the same address shows Signed in as Asha. You have 2 orders.

redirect() also works while a Client Component renders. In an event handler, like a button's onClick, the docs say to use router.push() from useRouter instead, as Linking and navigating shows.

After a form is sent: Server Actions and Route Handlers

A Server Action is a function marked "use server" that runs on the server when a form calls it. Your first Next.js app ended one with redirect("/") and saw a 303. Here is the tea shop's checkout, and this time the recorder also pressed the button in Chrome, with the page's JavaScript running:

1"use server";2 3import { redirect } from "next/navigation";4import { saveOrder } from "../_data/orders";5 6export async function placeOrder(formData: FormData) {7  await saveOrder(String(formData.get("tea")));8  redirect("/thanks");9}

In app/checkout/actions.ts, line 1 marks every function in the file as a Server Action. Line 7 saves the order with saveOrder from app/_data/orders.ts, a stand-in for a database. Line 8 sends the shopper to /thanks. In app/checkout/page.tsx, line 7 gives the form action={placeOrder}.

First, the form without JavaScript. Open the Network tab and pick POST /checkout, labeled Place order, before JavaScript: the recorder posted the form the way a browser does before the page's JavaScript has loaded. The answer is 303 with location: /thanks. 303, "see other", tells the browser to ask for the new address with a GET, a plain request for a page.

Then with JavaScript. The Steps tab is open on step 2, the click on Place order. It made one request: a fetch, not a document, POST /checkout with a next-action header that names the action. It answered 200 with text/x-component, an RSC payload: the data React needs to show a page, which Next.js's router asks for instead of HTML. There is no request for /thanks, yet the page shows Thank you!. The action's answer already held the /thanks page, and the router showed it in place, as after a click on a Link. One round trip, and no new HTML page. So this isn't an HTTP redirect either: the status is 200, and the router does the moving.

Step 3 presses the browser's Back button, and the shopper is on Checkout again, with no request at all. In a Server Action, redirect() adds the new address to the browser's history, so Back returns to the form. Everywhere else it replaces the current entry. (A second argument, RedirectType.push or RedirectType.replace, changes that; the docs say it has no effect in Server Components.)

In a Route Handler

A Route Handler is a route.ts file that answers requests with code instead of a page. It can call redirect() too:

1import { redirect } from "next/navigation";2 3export function GET() {4  redirect("/teas");5}

Line 3 exports GET, the function for GET requests, and line 4 redirects. /go answered 307 with location: /teas, as a prerendered page does. Pick /go/mint: its handler, in app/go/mint/route.ts, calls permanentRedirect() and answers 308. The Terminal tab lists ○ /go and ○ /go/mint: a GET handler that reads nothing from the request is run during the build, like a page. One case differs: when an HTML form is posted to a Route Handler, Next.js answers 303, as for a Server Action, so the browser asks for the new address with a GET instead of posting the form again.

307, 308 and 303: why the number matters

Where a redirect runs, and when, decides what comes back. Each row is one case from this lesson's recordings: what Next.js answered, and what the browser did next.

Only the 3xx answers are HTTP redirects. Their three codes all send the browser somewhere else; they differ in what the browser does next, and in what it and search engines remember. Each row is one status code:

The method: does the form go again?

Every request has a method: GET to ask for something, POST to send something, like a form. A 307 or a 308 tells the browser to repeat the same request at the new address, method and body included. The tea shop's newsletter form shows it. Old copies of the form, on other sites, still post to /signup, so next.config.ts sends that address on to /subscribe, where a Route Handler saves the email:

1import { redirect } from "next/navigation";2 3export async function POST(request: Request) {4  const form = await request.formData();5  console.log("New subscriber:", form.get("email"));6  redirect("/thanks");7}

In app/subscribe/route.ts, line 3 exports POST, line 4 reads the form, line 5 logs the email, and line 6 redirects to /thanks. In app/newsletter/page.tsx, line 5 is a plain HTML form that posts to /signup. In next.config.ts, line 7 sends /signup to /subscribe with permanent: false, which answers 307.

The Steps tab is open on the click on Subscribe. Chrome made three document requests for it. POST /signup answered 307, so Chrome sent POST /subscribe: the same method, with the form again. The Route Handler answered 303, so Chrome asked GET /thanks, and showed the page. Without the 303, the form would have gone a third time, to /thanks.

That's why Next.js answers 303 after a posted form, from a Server Action or a Route Handler, even when your code called permanentRedirect(). A 307 would send the order or the email again. Next.js's source says the same, in a comment above the line that picks 303 for a Route Handler (linked at the end of this lesson).

Remembered or not

Temporary or permanent also matters after the visit. A permanent redirect says the old address is gone for good. Browsers may remember a 308 and go straight to the new address next time, without asking the old one. Search engines replace the old address with the new one in their results. A temporary redirect asks them to keep the old address. So use permanentRedirect() or permanent: true only when the move is final: a browser that remembered it may keep skipping the old address even after you change your mind.

Check each one yourself. Every version below is one of this lesson's recordings. Before you click, guess its status.

1import { redirect } from "next/navigation";2 3export default function MenuPage() {4  redirect("/teas");5}

<!DOCTYPE html>
<html id="__next_error__">
  <head>
    <link rel="preload" as="script" fetchpriority="low" href="/_next/static/chunks/1x6obpmlu1_c2.js">
    <script src="/_next/static/chunks/06bs-nf19b2js.js" async=""></script>
    <script src="/_next/static/chunks/2ki52vdnbo2ft.js" async=""></script>
    <script src="/_next/static/chunks/3l_qmp-61z4yc.js" async=""></script>
    <script src="/_next/static/chunks/turbopack-3-ry682tkyiqk.js" async=""></script>
    <script src="/_next/static/chunks/3oh00mkbkq8u6.js" async=""></script>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
  </head>
  <body>
    <script id="_R_">…</script>
    <script src="/_next/static/chunks/1x6obpmlu1_c2.js" async=""></script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
  </body>
</html>

307 and 308 come from code that runs before anything of the page was sent, 303 from a posted form, and 200 from a page that had already started streaming. Older sites use 302 and 301 for temporary and permanent; some browsers turn a POST into a GET on those, which is the reason Next.js uses 307 and 308.

A list of redirects in next.config.ts

When you know the moves in advance, you don't need a page for each old address. next.config.ts, the project's settings file, can hold a list of them:

1import type { NextConfig } from "next";2 3const nextConfig: NextConfig = {4  cacheComponents: true,5  partialPrefetching: true,6  async redirects() {7    return [8      { source: "/menu", destination: "/teas", permanent: false },9      { source: "/blog/:slug", destination: "/journal/:slug", permanent: true },10    ];11  },12};13 14export default nextConfig;

/teas

Lines 4 and 5 are the settings create-next-app wrote, kept as they were. Line 6 adds redirects, an async function that returns the list. Each entry has a source, the old address, a destination, the new one, and permanent. Line 8 sends /menu to /teas for now. Line 9 moves every blog post for good: :slug matches one part of the address, whatever it is, and the destination reuses it.

In the Network tab, /menu answered 307 with location: /teas. Pick /blog/brewing-green-tea: 308, with location: /journal/brewing-green-tea. Pick the one with ?from=mail: the query came along, location: /journal/brewing-green-tea?from=mail. These answers have no HTML at all, only the new address as plain text. The Terminal tab has no /menu and no /blog: the list isn't made of routes. The docs say Next.js checks it before it looks for a page or a file, so an entry here wins even over a page at the same address.

Redirecting in proxy.ts: a first look

Some decisions depend on the request, and must still come before the page renders: the account page from earlier, for one. proxy.ts is the place for them. It's a file at the project's root, beside the app folder, whose function runs before a request reaches its route. (Before Next.js 16 it was called middleware.ts.) Here it guards the account page:

1import { NextResponse, type NextRequest } from "next/server";2 3export function proxy(request: NextRequest) {4  if (!request.cookies.has("session")) {5    return NextResponse.redirect(new URL("/sign-in", request.url));6  }7  return NextResponse.next();8}9 10export const config = { matcher: "/account" };

/sign-in

Line 3 exports a function named proxy, which gets the request. Line 4 checks for the session cookie, and line 5 answers with NextResponse.redirect and the full address of /sign-in, built from the request's own. (The Network tab shows it as /sign-in: Next.js sent the address on the same site as a path.) Line 7 lets every other request through. Line 10 is the matcher: proxy.ts runs only for /account. The page is the same as before.

Now /account without the cookie answers 307 with location: /sign-in: the page never started, so the status could still be a redirect. With session=Asha, it answers 200 with the orders. The Terminal tab adds a line under the routes, ƒ Proxy (Middleware), and the Steps tab shows Chrome's GET /account answered 307, then GET /sign-in.

Next.js's docs list the order: the redirects in next.config.ts first, then proxy.ts, then the routes. proxy.ts can do much more, and has its own lesson, proxy.ts. One warning already: a Server Action is a POST to its page, so a matcher that skips the page skips the action too. The docs say to check who is signed in inside each Server Action as well, not only in proxy.ts.

Why redirect() must not sit in try/catch

How does redirect() stop a page or an action in the middle? It throws: it creates an error and throws it, the way any JavaScript error stops the code around it (try...catch in the JavaScript course shows how). Next.js catches that error further up, outside your code, and turns it into the redirect. Here is the function, exactly as Next.js 16.4.3 has it:

export function redirect(
  /** The URL to redirect to */
  url: string,
  type?: RedirectType
): never {
  type ??= actionAsyncStorage?.getStore()?.isAction ? 'push' : 'replace'

  throw getRedirectError(url, type, RedirectStatusCode.TemporaryRedirect)
}

Line 5 says it returns never: a TypeScript type for a function that never comes back. Line 6 picks the history entry: push inside a Server Action, replace elsewhere. Line 8 throws. The error's message is NEXT_REDIRECT, and it carries the address and the status for Next.js to read.

So a catch around redirect() catches the redirect. The checkout's action wants to log saving errors, and wraps everything in try:

1"use server";2 3import { redirect } from "next/navigation";4import { saveOrder } from "../_data/orders";5 6export async function placeOrder(formData: FormData) {7  try {8    await saveOrder(String(formData.get("tea")));9    redirect("/thanks");10  } catch (error) {11    console.error("Could not place the order:", error);12  }13}

In the first version, the Steps tab ends step 2 on /checkout: the order was saved, and the shopper stayed. The Network tab's form without JavaScript got 200 and the Checkout page again, not a 303. The Terminal tab shows what next start printed, twice, once for each order: Could not place the order: Error: NEXT_REDIRECT. The catch on line 10 got Next.js's error, logged it as a failure, and the action ended normally.

There are two fixes, the second and third versions:

• Call redirect() after the try/catch. Only the work that can fail goes in try, and the catch on line 9 returns early. Line 13 runs outside it.
• Rethrow Next.js's errors. unstable_rethrow(error), on line 11 as the first line of the catch, throws the error again if it's one of Next.js's own, like the one from redirect() or notFound() (from Not found, forbidden and unauthorized), and does nothing otherwise. unstable_ in its name means it may still change.

Both answer the form with 303 and send the shopper to /thanks in Chrome. The same mistake in a page is quieter still:

1import { redirect } from "next/navigation";2 3export default function MenuPage() {4  try {5    redirect("/teas");6  } catch {7    return <p>The menu has moved.</p>;8  }9}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (6/6)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found├ ○ /menu├ ○ /teas└ ○ /teas/mint ○  (Static)  prerendered as static content

The build finished with no warning and lists ○ /menu. The catch on line 6 caught the redirect during the build, so the page Next.js stored is the one on line 7: in the Network tab, /menu answers 200 with The menu has moved. and no location. Nothing tells you, except the page itself.

Planning the tea shop's redirects

Each redirect has a best place: the earliest one that knows enough to decide. Each row is one place, in the order a request meets them:

Sort the tea shop's redirects: where does each one belong?

Common mix-ups

• "Every redirect answers with a 3xx status." No. Two answer 200: a page that had started streaming adds a meta refresh tag, and a Server Action called with JavaScript sends an RSC payload the router follows.
• "You write return redirect(…)." No. redirect() throws and never returns, and its type, never, tells TypeScript so. No return is needed.
• "A redirect in a page always answers 307." No. If the page has started to stream, as the account page had, the answer is 200 with a <meta http-equiv="refresh"> tag. Decide in proxy.ts for a real 307.
• "permanentRedirect() in a Server Action answers 308." No. A posted form gets 303 either way, and with JavaScript the router moves in place.
• "307 is the same as 302." No. A 307 keeps the method and the body; some browsers turn a POST into a GET on a 302.
• "redirect() works in a button's onClick." No. The docs say to use it while rendering, and router.push() in event handlers.
• "proxy.ts protects everything behind it." No. A matcher can miss a Server Action's POST. Check who is signed in inside each action too.
• "A permanent redirect is easy to take back." No. Browsers may remember a 308, and search engines replace the old address. Use it only for final moves.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page.

import { redirect } from "next/navigation";

export default function MenuPage() {
  redirect("/teas");
}

import { permanentRedirect } from "next/navigation";

export default function PeppermintPage() {
  permanentRedirect("/teas/mint");
}

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
  async redirects() {
    return [
      // /blog/<post> moved for good to /journal/<post>
    ];
  },
};

export default nextConfig;

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
  async redirects() {
    return [
      { source: "/menu", destination: "/teas", permanent: false },
      { source: "/blog/:slug", destination: "/journal/:slug", permanent: true },
    ];
  },
};

export default nextConfig;

"use server";

import { permanentRedirect } from "next/navigation";
import { saveOrder } from "../_data/orders";

export async function placeOrder(formData: FormData) {
  await saveOrder(String(formData.get("tea")));
  permanentRedirect("/thanks");
}

"use server";

import { redirect } from "next/navigation";
import { saveOrder } from "../_data/orders";

export async function placeOrder(formData: FormData) {
  try {
    await saveOrder(String(formData.get("tea")));
    redirect("/thanks");
  } catch (error) {
    console.error("Could not place the order:", error);
  }
}

"use server";

import { redirect } from "next/navigation";
import { saveOrder } from "../_data/orders";

export async function placeOrder(formData: FormData) {
  try {
    await saveOrder(String(formData.get("tea")));
  } catch (error) {
    console.error("Could not place the order:", error);
    return;
  }
  redirect("/thanks");
}

import { Suspense } from "react";
import { cookies } from "next/headers";
import { redirect } from "next/navigation";

async function Orders() {
  const name = (await cookies()).get("session")?.value;
  if (!name) {
    redirect("/sign-in");
  }
  return <p>Signed in as {name}. You have 2 orders.</p>;
}

export default function AccountPage() {
  return (
    <main>
      <h1>Your account</h1>
      <Suspense fallback={<p>Checking who you are…</p>}>
        <Orders />
      </Suspense>
    </main>
  );
}

import { NextResponse, type NextRequest } from "next/server";

export function proxy(request: NextRequest) {
  if (!request.cookies.has("session")) {
    return NextResponse.redirect(new URL("/sign-in", request.url));
  }
  return NextResponse.next();
}

export const config = { matcher: "/account" };

Check your understanding

For each question, ask where the redirect runs, and whether the response had already started.

Key takeaways

• An HTTP redirect is an answer with no page: a 3xx status code and a location header. The browser asks for the new address on its own.
• redirect() answers 307 and permanentRedirect() answers 308, from a page that hasn't started streaming or a GET Route Handler. After a posted form, both answer 303.
• Once a page has started streaming, its redirect answers 200 with a <meta http-equiv="refresh"> tag, and the browser loads the new address as a new page.
• With JavaScript, a Server Action that redirects sends one POST, and its answer already holds the new page. The router shows it in place, and adds it to the history.
• 307 and 308 keep the method and the body; 303 makes it a GET. Permanent redirects are remembered by browsers and search engines.
• Known moves go in next.config.ts; decisions from the request go in proxy.ts; what only the page or the action knows goes in your code.
• redirect() throws. Keep it out of try, or call unstable_rethrow(error) first in the catch.

Coming next: Templates and the file hierarchy. It shows how a folder's special files nest inside each other, and template.tsx, a layout that starts fresh on each page.