HTTP Headers

Introduction

You can set custom HTTP headers on the response of a given path. This allows you to modify the caching behavior or configure access control. You can apply HTTP headers to static routes and redirects.

This feature was added in gatsby@5.12.0.

Usage

Use the headers config option inside gatsby-config:

The headers option accepts an array of objects in the following shape:

• source: A request path pattern. See path matching for more details on its syntax. The paths /slug and /slug/ are equivalent since Gatsby normalizes trailing slashes.
• headers: An array of objects in the following shape:
  • key: The case-insensitive name of the header
  • value: The value of the header

Overriding behavior

The order in which you insert values into headers doesn’t matter because Gatsby determines the specificity of each source path.

If two headers match the same path and set the same header key, the entry with the more specific source path will override the other. Examples of the overriding behavior are included below.

Once entries with matching paths are handled, all header entries are merged together into one array of headers.

Generally speaking, the headers get created in this order. Note that static entries can override the first two:

1. Default headers
2. Entries with path matching on source
3. Entries with a static source path

Examples

To help illustrate how header overrides work, here are some examples. The input represents what you can pass to the headers config option and the output is what Gatsby produces for the given matched path.

Non-overlapping keys

Overlapping keys

This example also shows that static entries will override ones with path matching.

Specificity

Gatsby internally adds scores to each path matching entry and sorts the entries by that score — the entry with the highest specificity will override other matching entries. In the following example, /some-path/:slug overrides the rest because it’s more specific than * and /some-path/*.

Path matching

As outlined in the previous paragraphs, you can not only define static source paths like /some-path/ but also ones with path matching. This allows you to target more than one path, opening up more flexibility. You can currently use two path matchers:

• Dynamic: Matches a path segment (no nested paths)
• Wildcard: Matches every path segment after its definition

Dynamic path

You can use a colon (:) to declare a dynamic path. For example, /some-path/:slug will match /some-path/foo and /some-path/bar.

Wildcard path

You can use an asterisk (*) to declare a wildcard path. For example, /some-path/* will match /some-path/foo and /some-path/foo/bar.

Defaults

By default, Gatsby applies HTTP caching headers to its assets following the guide Caching Static Sites. You can find the specific values on GitHub.

You can use the headers option to override these defaults.

Additional resources

• HTTP Headers MDN documentation