Static Site Generators in Production

Netlify Redirects and Rewrites for Static Sites

Netlify's redirect engine is one of its most useful features for static sites, and one of the easiest to misconfigure. The same syntax handles permanent moves after a migration, clean URLs for single-page apps, proxying an API to avoid CORS, and sending German-speaking visitors to /de/. The rules look simple, but ordering, shadowing and the difference between redirects and rewrites catch almost everyone at least once.

This guide covers both configuration files, status codes and when each applies, splats and placeholders, the shadowing rule that makes redirects "not work", proxy rewrites, and conditions for country and language. It is part of Netlify vs Vercel Deployment Strategies.

Prerequisites

  • A static site deployed on Netlify.
  • A list of the redirects you need, with old and new paths.
  • The Netlify CLI for local testing: npm install -D netlify-cli.

Two Places to Write Rules

Rules can live in a _redirects file in the publish directory, or in [[redirects]] blocks in netlify.toml at the repository root. Netlify processes _redirects first, then netlify.toml, and within each file the first matching rule wins.

# _redirects
/old-guide/          /guides/new-guide/      301
/blog/*              /articles/:splat        301
/docs/:version/*     /docs/:splat?v=:version 302
/api/*               https://api.example.com/:splat  200
/*                   /index.html             200

# netlify.toml
[[redirects]]
  from = "/old-guide/"
  to = "/guides/new-guide/"
  status = 301

[[redirects]]
  from = "/api/*"
  to = "https://api.example.com/:splat"
  status = 200
  headers = { X-From = "netlify" }

_redirects is compact for long lists generated by a script. netlify.toml is clearer for a handful of complex rules with conditions or headers. Using both is supported, but pick one as the primary source so people know where to look.

How Netlify evaluates a request against redirect rules A request is matched against _redirects rules first, then netlify.toml rules, top to bottom. For each matching rule, Netlify checks whether a file exists at the path. If it does and the rule is not forced, the file is served. Otherwise the rule applies: a 301 or 302 redirects the browser, a 200 serves another path or proxies an external URL, and a 404 serves custom content. First matching rule, then the shadowing check request _redirects rules then netlify.toml top to bottom file exists at source path and rule not forced? yes: serve the file rule is shadowed no: apply the rule 301/302 → redirect 200 → rewrite or proxy 404 → custom content add ! to the status (301!) to force a rule even when a file exists
Shadowing is why a redirect from a page that still exists appears to do nothing.

Status Codes

  • 301 — permanent redirect. Browsers cache it; search engines move ranking signals to the new URL. Use for completed moves.
  • 302 — temporary redirect. Not cached long-term. Use while testing, and for redirects that may change, such as "latest version" links.
  • 200 — rewrite. The browser keeps the original URL and receives content from the target. Used for single-page app fallbacks, serving one folder under another path, and proxying.
  • 404 — serve custom content with a 404 status, for example a section-specific not-found page: /docs/* /docs/404.html 404.

Netlify also accepts 307 and 308, which behave like 302 and 301 but preserve the request method, relevant only when a form posts to a moved URL.

Splats and Placeholders

A splat (*) at the end of the source matches the rest of the path, available as :splat in the target. Placeholders (:name) match one path segment each:

/blog/:year/:month/:slug/   /articles/:slug/   301
/docs/v1/*                  /docs/:splat       301

The first collapses thousands of date-based URLs from an old blog into one rule. The second retires a versioned docs path. Pattern rules are easier to review than long exact lists and cheaper to maintain, so look for patterns in a migration mapping before generating one line per URL. Query parameters can also be matched: /search q=:term /find/:term 301 redirects /search?q=astro to /find/astro.

Shadowing and Forcing

By default, Netlify serves a file if one exists at the requested path, even when a rule matches. This "shadowing" is intended: it lets a catch-all rewrite like /* /index.html 200 sit at the end of the file without hijacking real pages and assets.

It surprises people during migrations. If the old page still exists in the build output — because the generator still produces it, or a stale file remains — the redirect silently does nothing. Either remove the old file or force the rule with !:

/pricing-old/   /pricing/   301!

Force only rules that need it. Forcing a catch-all rewrite would send every asset request to index.html.

Shadowing also explains trailing-slash surprises. A rule from /pricing does not fire for a request to /pricing/, and Netlify's pretty URL handling may already serve /pricing/index.html for both. Write sources in the form your old site actually used, check the analytics or server logs from the old host for the exact variants readers requested, and add both forms where old links were inconsistent. A quick way to find shadowed rules after a deploy is to request every source path in the list and flag any that return 200 instead of the expected redirect status.

Proxying With Rewrites

A 200 rule to an absolute URL makes Netlify fetch the target and return it under your domain. Common uses on static sites:

  • Avoiding CORS for a third-party API called from the browser: /api/* https://api.example.com/v2/:splat 200.
  • Serving another deployment under a path: /blog/* https://blog-site.netlify.app/:splat 200 merges two sites under one domain.
  • Analytics proxies so first-party requests reach an analytics endpoint.
Redirect compared with a proxy rewrite With a 301 redirect, the browser receives a Location header and makes a second request to the new host, whose URL appears in the address bar. With a 200 proxy rewrite, Netlify fetches the target itself and returns the response under the original URL, so the browser makes one same-origin request and no CORS check is needed. Who makes the second request 301 redirect browser Netlify api.example.com Location header back browser calls the API (CORS applies) 200 proxy rewrite browser Netlify api.example.com Netlify fetches
A proxy keeps the request same-origin, which is why it removes CORS problems.

Proxied responses are cached by Netlify's CDN according to the target's Cache-Control headers. Add headers = { Authorization = "..." } in netlify.toml to send a header to the target, but never put secrets in _redirects, which is published with the site.

Country and Language Rules

Rules can match visitor country and browser language, which is useful for localised static sites:

/   /de/   302   Language=de
/   /fr/   302   Country=fr,be,ch  Language=fr
/   /en/   302

Order matters: specific rules first, then the fallback. Use 302, not 301, because the right destination depends on the visitor and should not be cached as permanent. Always provide a visible language switcher as well; geolocation and headers are hints, not the reader's choice.

Language and country rules for the site root A request for the root is checked against three rules in order. A browser preferring German goes to /de/. A visitor from France, Belgium or Switzerland with French preferred goes to /fr/. Everyone else goes to /en/. All three use 302 redirects. Routing "/" by language and country GET / Language=de Country=fr,be,ch and Language=fr no condition (fallback) 302 → /de/ 302 → /fr/ 302 → /en/ only the root is routed; deep links keep the language the reader followed
Route only the entry point; never redirect a deep link to a different language.

Testing Locally and in Previews

netlify dev serves the site locally with the redirect engine applied, so rules can be checked with curl -I before pushing. Deploy previews run the same rules on real infrastructure; check the redirect list against the preview URL in CI, as described in Netlify Deploy Previews for Every Pull Request. Netlify's deploy summary also reports how many redirect rules were processed, which quickly reveals a file that was not copied into the publish directory.

Measured Impact

A content site moving from WordPress to Eleventy on Netlify needed 4,800 redirects. A generated _redirects file with three placeholder rules for date-based post URLs and 1,200 exact rules for pages covered them all. The first deploy showed 38 "redirects" that did nothing, all shadowed by old HTML files still produced by a legacy template; removing those files fixed them without forcing. Search Console reported the migration's crawl errors falling from 4,100 to 60 within three weeks.

Pitfalls & Rollback

  • _redirects not in the publish directory. It must be in the built output; many generators need it in public/ or static/.
  • Catch-all before specific rules. /* /index.html 200 must be last.
  • Chains. Redirect old URLs straight to their final destination, not through intermediate moves, and re-check old rules whenever a page moves again.
  • Secrets in proxy rules. Put headers with credentials only in netlify.toml, and prefer an edge function for anything sensitive.
  • Rollback: Netlify deploys are atomic; publishing the previous deploy restores the previous rules.

Conclusion

Netlify's redirect engine covers most routing needs of a static site without code: 301s for moves, 302s for temporary and conditional routing, 200 rewrites for fallbacks and proxies, and 404 rules for custom error pages. Keep rules in one primary file, order them from specific to general, remember that existing files shadow rules unless forced, test with netlify dev and deploy previews, and generate long lists from a mapping rather than editing them by hand.

FAQ

What is the difference between a redirect and a rewrite on Netlify?

A redirect (status 301 or 302) sends the browser to a new URL, which appears in the address bar. A rewrite (status 200) serves content from another path or URL while the browser keeps the original URL. Rewrites to external URLs act as a proxy.

Why is my Netlify redirect being ignored?

Most often because of shadowing. By default, a rule does not apply if a file exists at the source path. Add an exclamation mark after the status code, for example 301!, to force the rule even when a file exists.

Should I use _redirects or netlify.toml?

Either works and both can be used together; rules in _redirects are processed before those in netlify.toml. _redirects is compact for long lists, netlify.toml supports headers conditions and is easier to review for complex rules. Pick one as the main source to avoid confusion.

Can Netlify redirect by country or language?

Yes. Rules can include Country and Language conditions, matched against the visitor's geolocation and Accept-Language header, which is useful for sending visitors to a localised version of a static site.