Custom headers

Build & Deploy

Add custom response headers in void.config.ts with routing.headers. Keys are URL patterns; values are lists of "Name: value" strings.

On this pageAdd security or cache headers · Scope headers to some paths · See how headers work with frameworks

This example sets cache and security headers by URL pattern.

{
  "routing": {
    "headers": {
      "/assets/*": ["Cache-Control: public, max-age=31536000, immutable"],
      "/*": ["X-Frame-Options: DENY", "X-Content-Type-Options: nosniff"],
      "/*.html": ["Cache-Control: no-cache"]
    }
  }
}

Matching rules

• Pattern keys start with /. * matches any characters including /.
• Header values use the Name: value format. The value can contain colons.
• All matching rules are merged. If several rules set the same header, the last match wins.
• Your Cache-Control overrides the built-in default. The default applies when no rule matches.

Where rules apply

Header rules apply to static assets, SSR pages and API responses. This includes hashed assets served from cache.

You can add headers to hashed assets. The platform still controls their caching and encoding. Rules cannot replace Cache-Control, Content-Type, Content-Encoding, Content-Length, Content-Range, Accept-Ranges, or Transfer-Encoding on these files.

Header rules do not apply to ISR cache responses.

Cookie headers

On an SDK platform, apps usually share one application domain, such as apps.example.com. On a platform deploy, the SDK changes two headers on every hostname of the app, including custom domains:

• The SDK ignores Set-Cookie in header rules.
• The SDK removes the "cookies" directive from Clear-Site-Data in header rules. Other directives, such as "cache" and "storage", still apply.
• The SDK ignores the full value of a Clear-Site-Data rule that includes "*". The response then keeps the Clear-Site-Data value from your app's response, without "cookies". If that value also includes "*", the response has no Clear-Site-Data.

This stops a header rule from setting or clearing cookies for other apps on the domain. The limits apply only to header rules. Your app's own responses can still set cookies and send Clear-Site-Data. On a shared domain, those can affect other apps. See Domains and Resources.

In void dev, with void deploy --platform cloudflare, and on other runtimes, header rules apply both headers as written.

Framework _headers files

The SDK reads _headers files from supported frameworks. Your routing.headers rules run afterward and can override framework defaults. No extra setup is needed.

Next steps

NextRedirectsPreviousEdge prerenderingZoneAll Build & Deploy pages