# Redirects and headers

> _redirects, _headers, vercel.json and netlify.toml files for static sites — what works and what doesn't.

Source: https://livops.dev/en/docs/redirects-headers

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.

```text
# 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
```

- `from` must 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.
- `:name` matches one path segment. A trailing `*` matches everything else and becomes `:splat` in 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:

```text
/*
  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:

```json
{
  "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`: uses `statusCode` if present; otherwise `permanent: false` is 307, and anything else 308.
- `rewrites` become 200 rules.
- A trailing `:name*`, `:name+` or `(.*)` is treated as `*`. Only the trailing form.
- `cleanUrls` isn't needed: a request for `/about` already serves `about.html`. `trailingSlash` is ignored.
- `vercel.json` rules are checked after the `_redirects` and `_headers` rules.

## netlify.toml

For a site moved from Netlify, `[[redirects]]` and `[[headers]]` in `netlify.toml` are read:

```toml
[[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"
```

- `:name` and `*` in `from`, `to` and `for` work as in `_redirects`, and the allowed statuses are the same.
- If `status` is missing — **301**.
- A rule with `conditions` (country, language, role) is skipped. The `[build]` section is not read here.
- `netlify.toml` rules are checked after `_redirects`, `_headers` and `vercel.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 to `https://...` 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.
