Build and configure
Redirects and headers
_redirects, _headers, vercel.json and netlify.toml files for static sites — what works and what doesn't.
For a static site, you control redirects and HTTP headers with files. The files must sit at the root of the build output (for example, public/_redirects → dist/_redirects). vercel.json and netlify.toml may also sit at the project root: for a site that is built, they are carried into the release automatically (unless the build output already has a file of that name).
The files are read on every request, so changes take effect as soon as the deploy finishes.
_redirects
Each line: from to [status]. A line starting with # is a comment.
# old pages
/old-page /new-page 301
/blog/:slug /news/:slug 301
/docs/* /help/:splat 302
# SPA or internal rewrite
/app/* /app/index.html 200
# redirect to an external URL
/telegram https://example.com/contact 302
# page doesn't exist
/private/* /404 404
frommust start with/.- If no status is given — 301.
- Allowed statuses: 200 (rewrite within the site), 301, 302, 307, 308, 404. A line with any other status is dropped.
:namematches one path segment. A trailing*matches everything else and becomes:splatin the target.- The first matching rule wins.
- A
!after the status is accepted but has no special meaning. - The query string is kept:
/old?utm_source=tg→/new?utm_source=tg. If the target has its own?..., that one is kept instead.
_headers
A path line, followed by Name: value lines indented with whitespace:
/*
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin
/assets/*
Cache-Control: public, max-age=31536000, immutable
:name and * in paths work just like in _redirects.
vercel.json
For sites moved from Vercel, three keys in vercel.json are read:
{
"redirects": [
{ "source": "/old", "destination": "/new", "permanent": true }
],
"rewrites": [
{ "source": "/app/:path*", "destination": "/app/index.html" }
],
"headers": [
{
"source": "/assets/(.*)",
"headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000" }]
}
]
}
redirects: usesstatusCodeif present; otherwisepermanent: falseis 307, and anything else 308.rewritesbecome 200 rules.- A trailing
:name*,:name+or(.*)is treated as*. Only the trailing form. cleanUrlsisn’t needed: a request for/aboutalready servesabout.html.trailingSlashis ignored.vercel.jsonrules are checked after the_redirectsand_headersrules.
netlify.toml
For a site moved from Netlify, [[redirects]] and [[headers]] in netlify.toml are read:
[[redirects]]
from = "/old"
to = "/new"
status = 301
[[redirects]]
from = "/app/*"
to = "/app/index.html"
status = 200
[[headers]]
for = "/assets/*"
[headers.values]
Cache-Control = "public, max-age=31536000, immutable"
:nameand*infrom,toandforwork as in_redirects, and the allowed statuses are the same.- If
statusis missing — 301. - A rule with
conditions(country, language, role) is skipped. The[build]section is not read here. netlify.tomlrules are checked after_redirects,_headersandvercel.json.
Limits
- Each file is limited to 1000 lines and 64 KB.
- No rewrites (proxying) to another site. The target of a 200 or 404 rule must start with
/; a 200 rule tohttps://...is dropped. Redirect to external URLs only with 301/302/307/308. - These headers can’t be set (they’re silently dropped):
Set-Cookie,Location,Content-Length,Content-Encoding,Transfer-Encoding,Connection.
404 and SPA
- If the build output has a
404.html, it’s served with a real 404 status. - If an app with a client-side router (React Router, Vue Router, etc.) is detected, page requests without a file extension get
index.html. A missing image or script still returns 404.