Custom Headers

Define custom response headers in void.config.ts using the routing.headers field. Keys are URL patterns, values are arrays of "Name: value" strings.

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

Rules

• Pattern keys start with /. * matches any characters including /.
• Header values use Name: value format. The value may contain colons.
• All matching rules are merged. When multiple rules set the same header name, the last match wins.
• User-defined Cache-Control overrides the built-in default. The default still applies when no rule matches.
• With authentication, responses to requests that send cookies or credentials stay private, and auth endpoints stay uncached, during local development, with void deploy --platform cloudflare, and on other runtimes. On a Void platform, a Cache-Control rule replaces the app's value, so do not match signed-in pages or /api/auth/* with a public cache rule.
• Rules apply to matching error responses too, including 404 responses. An immutable cache rule can therefore cache a missing file. Use immutable caching only for URLs that change when their content changes.

Scope

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

For hashed assets, you can add headers, but the platform keeps control of caching and response 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 a Void platform, set cookies in your app's response. Header rules ignore Set-Cookie, remove "cookies" from Clear-Site-Data, and ignore Clear-Site-Data rules containing "*". You can use directives such as "cache" and "storage" in header rules.

These limits apply on all of your app's hostnames, including custom domains, to protect cookies for other apps on the shared domain. Your app's own cookie headers can still affect those apps, so scope cookies carefully. See Domains and Resources.

During local development, with void deploy --platform cloudflare, and on other runtimes, header rules apply both headers as written.

Framework _headers files

On a Void platform, Void reads _headers files produced by supported frameworks. Your routing.headers rules run afterward, so they can override framework defaults.

For native Cloudflare framework deployments, put a _headers file in your framework's public asset directory to configure static asset responses. Void includes the built file when it uploads a Worker version, including deployments that keep existing Worker secrets. These rules do not apply to responses generated by a Worker.