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
headers config option inside
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/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
The order in which you insert values into
headers doesn’t matter because Gatsby determines the specificity of each
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:
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.
This example also shows that static entries will override ones with path matching.
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
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
You can use a colon (
:) to declare a dynamic path. For example,
/some-path/:slug will match
You can use an asterisk (
*) to declare a wildcard path. For example,
/some-path/* will match
You can use the
headers option to override these defaults.