> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sevalla.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Static Sites - Headers

> Find out how to add custom HTTP headers to your static sites in Sevalla.

If a static site has a `_headers` file in the repository's root directory, Sevalla will parse the file's contents and apply the custom header rules to matching responses.

## Header rule format and examples

Each header rule starts with a path on its own line, followed by one or more indented header definitions in the format `Header-Name: value`. Any line beginning with `#` will be treated as a comment and ignored. Paths are case-sensitive.

For example:

```text theme={null}
# Security headers for all pages
/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff

# Cache static assets for one year
/assets/*
  Cache-Control: public, max-age=31536000, immutable

# Custom header for the API
/api/*
  X-Api-Version: 2.0
```

Header rules are processed from top to bottom, and all matching rules are applied. If multiple rules match the same path, their headers are combined. When the same header name appears in multiple matching rules, the values are merged with a comma separator.

## Applying headers to all pages

Use the `/*` wildcard pattern to set headers that apply across your entire site:

```text theme={null}
/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin
  Permissions-Policy: camera=(), microphone=(), geolocation=()
```

This is useful for security headers, which typically need to be present on every response.

## Wildcards

An asterisk (`*`) represents a wildcard, which matches any characters in a path, including slashes. For example:

```text theme={null}
/images/*
  Cache-Control: public, max-age=86400
```

This applies the `Cache-Control` header to any path under `/images/`, such as `/images/logo.png` or `/images/icons/arrow.svg`.

You can also use wildcards within a path segment to match file extensions:

```text theme={null}
/*.css
  Cache-Control: public, max-age=31536000

/*.js
  Cache-Control: public, max-age=31536000
```

> **Note:** Wildcards are greedy - `/*.svg` will match both `/logo.svg` and `/images/icons/logo.svg`, as the wildcard crosses directory boundaries.

## Placeholders

You can use placeholders to match a single path segment. A placeholder starts with `:` followed by a name and matches any characters except `/`. For example:

```text theme={null}
/docs/:version/*
  X-Docs-Version: latest
```

In this example, the rule matches paths like `/docs/v2/getting-started` or `/docs/v3/api-reference`, but not `/docs/` by itself.

## Combining multiple rules

When multiple rules match a request path, all of their headers are applied to the response. If the same header name appears in more than one matching rule, the values are combined with a comma separator.

For example:

```text theme={null}
/*
  Cache-Control: public
  X-Custom: global

/api/*
  Cache-Control: no-store
  X-Api: true
```

A request to `/api/users` matches both rules. The resulting headers would be:

* `Cache-Control: public, no-store`
* `X-Custom: global`
* `X-Api: true`

To avoid conflicting cache directives, place more specific rules carefully and avoid overlapping `Cache-Control` values between wildcard and specific rules.

## Common use cases

### Security headers

```text theme={null}
/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin
  Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
  Permissions-Policy: camera=(), microphone=(), geolocation=()
```

### Caching static assets

```text theme={null}
/assets/*
  Cache-Control: public, max-age=31536000, immutable

/*.html
  Cache-Control: public, max-age=0, must-revalidate
```

### Custom headers for an API path

```text theme={null}
/api/*
  Access-Control-Allow-Origin: *
  X-Api-Version: 2.0
```

### CORS for font files

```text theme={null}
/fonts/*
  Access-Control-Allow-Origin: *
```

## Restricted headers

Certain headers are managed by the platform and cannot be overridden. If a restricted header appears in your `_headers` file, it will be silently ignored. The following headers are restricted:

* `Accept-Ranges`
* `Age`
* `Allow`
* `Alt-Svc`
* `Connection`
* `Content-Encoding`
* `Content-Length`
* `Content-Range`
* `Date`
* `Location`
* `Server`
* `Trailer`
* `Transfer-Encoding`
* `Upgrade`