Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 37 ยท Domains, HTTPS and Redirects

Redirects and Rewrites

Write redirect and rewrite rules for Vercel (vercel.json) and Netlify (_redirects and netlify.toml): status codes, splats, SPA fallbacks, proxying, country rules and rule order.

A redirect tells the browser to go somewhere else: the address bar changes. A rewrite quietly serves different content for the same address: the address bar stays. You need both: redirects when you rename a page or move a domain, rewrites for single-page apps, clean URLs and proxying an API.

The platforms cannot run here, so the configuration files below are read-only examples. The runnable blocks are JavaScript stand-ins that model the matching rules so you can experiment. Always test real rules on a preview deployment.

Redirect versus rewrite

Redirect Rewrite
Address bar changes stays the same
Browser requests two (the original, then the target) one
Search engines follow the new URL index the original URL
Typical use moved pages, www to apex, old domain to new SPA fallback, proxying, A/B routes

Redirect status codes matter: 301 and 308 are permanent (search engines transfer ranking, browsers cache them hard), 302 and 307 are temporary. 308 and 307 additionally preserve the HTTP method, which matters for POST.

Netlify: _redirects and netlify.toml

Netlify reads a plain text file named _redirects from your publish directory. Each line is from to status:

TEXT
# permanent move
/old-blog/*   /blog/:splat   301
# single page app fallback (a rewrite: status 200)
/*            /index.html    200
# proxy an API through your domain
/api/*        https://api.example.test/:splat   200

The first matching rule wins, so put specific rules above the catch-all. The same rules can live in netlify.toml:

TOML
[[redirects]]
  from = "/old-blog/*"
  to = "/blog/:splat"
  status = 301

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Status 200 means rewrite. By default a rule does not override a real file at the same path: add force = true (or 200! in _redirects) to override. Netlify rules can also match on country or language (Country=de, Language=fr) and on roles (Role=admin).

Vercel: vercel.json

Vercel keeps rules in vercel.json, in two separate arrays:

JSON
{
  "redirects": [
    { "source": "/old-blog/:path*", "destination": "/blog/:path*", "permanent": true }
  ],
  "rewrites": [
    { "source": "/api/:path*", "destination": "https://api.example.test/:path*" },
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

permanent: true sends 308; permanent: false sends 307; you can set statusCode explicitly. source uses a path-to-regexp style: :name captures one segment, :path* captures the rest, and has/missing conditions can match headers, cookies, queries or the host. Framework projects (Next.js, Astro, SvelteKit...) also have their own redirect configuration; use whichever your framework documents.

Pick the right tool

Redirect The address changes.
Rewrite Same address, other content.
Proxy A rewrite to another origin.
SPA fallback Unknown paths serve index.html.

Specific rules first, catch-all last.

1 / 2

A matcher you can run

The stand-in below parses _redirects style lines, supports :splat and *, and applies "first match wins". It is a teaching model and does not implement every Netlify feature.

JS Redirect rules stand-in

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Rule order and loops

Because the first match wins, a catch-all above a specific rule makes the specific rule dead. A second hazard is a redirect loop: /a to /b and /b to /a. Browsers give up after about twenty hops with an error. This stand-in follows a chain and reports loops, which is a useful check to run on a rule list:

JS Loop detector stand-in

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Chains are also slow: each hop costs a round trip. Point old URLs directly at the final destination.

Good habits

  • Use permanent redirects only when you mean it: browsers cache them for a long time.
  • Keep a list of old URLs when you restructure a site; each one deserves a redirect.
  • Never redirect everything to the home page: it confuses users and search engines.
  • Query strings: Netlify forwards them by default; Vercel forwards them unless you disable it. Check your rule on a preview.
  • Prefer redirects at the platform edge over JavaScript redirects: they are faster and work without scripts. For logic that needs code (per-user rules, A/B tests), use middleware or an edge function instead of a static rule.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which Netlify status code makes a rule a rewrite instead of a redirect?

    Status 200 serves the target content while keeping the original URL, so it behaves as a rewrite or proxy.
  2. 2. A redirect list has /* -> /index.html at the top. What happens to rules below it?

    Order matters. Put specific rules above catch-alls.
  3. 3. Which Vercel setting produces a 308 status?

    permanent true sends 308 (a method-preserving permanent redirect); false sends 307.
  4. 4. Why should old URLs redirect straight to their final destination?

    Every extra hop adds latency, and cycles end in an error.

Summary

  • Redirects change the address; rewrites keep it.
  • Netlify uses _redirects or netlify.toml; Vercel uses vercel.json.
  • First match wins, so order specific rules before the SPA fallback.
  • Choose 301/308 for permanent and 302/307 for temporary moves.
  • Test rules on a preview deployment and avoid chains and loops.

Next: Response Headers and Security