Skip to main content
A _headers file sets HTTP response headers for matching paths on a static site: security headers, cache lifetimes, CORS and anything else a browser reads from a response. Sevalla reads the file at every deployment and adds its headers at the edge to every response for a matching path, including redirects and 404 pages.

​
Add a headers file

1

Create the file

Create a file named _headers, with no extension, so that it ends up in the publish directory. Many generators copy the files of a public folder into their output. Sevalla also finds the file in the build’s root directory, but looks in the publish directory first.
2

Add the rules

Write each path on its own line, with its headers on the lines below it. See Rule syntax.
3

Deploy

Commit and push the file, then deploy the site if the push doesn’t.
The deployment’s log says it found the _headers file, then Headers processed successfully!. Sevalla doesn’t publish the file itself. Changes apply from the next deployment. To check a header, request a page and read the response, for example with curl -I https://shop.example.com/.
If any line can’t be parsed, the log shows There were errors while parsing your header rules: with the line and the reason, and the deployment is published without any of the file’s headers. The deployment still succeeds, so check the log after you change the file.

​
Rule syntax

_headers
  • A line that starts with / is a path. The header lines below it apply to it, until the next path. Paths must start with /: full URLs aren’t supported.
  • A header line is Name: value. Indenting it is optional. Everything after the first : is the value.
  • A line that starts with # is a comment. Blank lines and lines without a : are ignored.
  • The same header twice under one path gives one header with both values, separated by , .
A line Sevalla can’t read fails with Path should come before header "<name>" (a header line before any path), Missing header name or Missing header value.

​
Path patterns

  • The whole path must match, and case matters. The query string isn’t part of the path.
  • A trailing slash matters. /about doesn’t match /about/. With pretty URLs on, pages are served at URLs that end in /: write /about/, or /about/* for the page and everything under it.
  • * matches any characters, slashes included, anywhere in the path.
  • :name matches one path segment, the text between two slashes.

​
How rules combine

Every rule whose path matches applies. When more than one matching rule sets the same header, the response gets one header with all their values, separated by , , in the order of the file:
_headers
A request for /api/health.json gets Cache-Control: public, no-store and X-Site: acme. To avoid contradictory values, don’t set the same header in overlapping rules.

​
Headers Sevalla sets

A header in your _headers file replaces Sevalla’s value for that header. A Cache-Control you set changes how long browsers keep a file, not the edge cache: Sevalla’s edge keeps files for 30 days or until the next deployment either way. See Networking and caching.

​
Restricted headers

Sevalla manages these headers and ignores them in a _headers file, without an error: Accept-Ranges, Age, Allow, Alt-Svc, Connection, Content-Encoding, Content-Length, Content-Range, Date, Location, Server, Trailer, Transfer-Encoding and Upgrade. Header names aren’t case-sensitive here.

​
Examples

​
Security headers

_headers

​
Cache files that keep their names

Browsers keep files other than HTML for 30 days by default. If a file keeps its name across deployments, such as /styles.css or /images/logo.png, visitors can see the old version after you deploy. Make browsers check for a new version on every visit, or keep the file for a shorter time:
_headers
Files with a content hash in their name, like the ones Vite and Astro write to /assets/, can be cached for a year with immutable, as in the rule syntax example.

​
Limit CORS to one origin

Every response allows any origin by default. To allow only your own:
_headers