Security headers on Vercel

Clear the header findings on a Vercel site from one file. Set HSTS, CSP and the other security headers in vercel.json, with every step cited to Vercel docs.

Vercel reads custom response headers from the headers array of vercel.json, a file in the root directory of the project. Each entry pairs a source pattern, matched against the request path, with the headers to send when it matches. Optional has and missing conditions narrow an entry to requests with or without a given header, cookie, host or query value.

Create vercel.json in the root of the project if it is not there yet, with one entry whose source is /(.*), the pattern Vercel uses in its own example for every route. Each section below adds one object to the list inside that entry.

vercel.json

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Content-Type-Options", "value": "nosniff" }
      ]
    }
  ]
}

Source: Vercel docs: vercel.json headers

Strict-Transport-Security (HSTS)

Vercel already sends strict-transport-security: max-age=63072000 on deployment responses. That is two years.

To send a value of your own, such as one with includeSubDomains, add the header to the list. Then check which value the live response carries.

vercel.json, inside the list

{ "key": "Strict-Transport-Security", "value": "max-age=63072000; includeSubDomains" }

Add includeSubDomains only when every subdomain answers over HTTPS.

Sources: Vercel docs: response headers and Vercel docs: vercel.json headers

Content-Security-Policy (CSP)

Vercel advises starting with the Content-Security-Policy-Report-Only header, which reports what a policy would stop without stopping it. Its advice is to enforce the policy only once it breaks nothing. The same page advises against unsafe-inline and unsafe-eval and suggests nonces or hashes for any inline script the site needs.

Start with the report-only header in the list.

vercel.json, inside the list

{ "key": "Content-Security-Policy-Report-Only", "value": "default-src 'self'" }

Once the reports show the policy breaks nothing, change the key to Content-Security-Policy to enforce it, as Vercel advises.

vercel.json, inside the list

{ "key": "Content-Security-Policy", "value": "default-src 'self'" }

A working policy names every origin your pages load from. The CSP fix guide linked below shows how to build one.

Sources: Vercel docs: CSP guidance and Vercel docs: vercel.json headers

X-Frame-Options

Add X-Frame-Options to the list. Vercel sets this header in its own example the same way.

vercel.json, inside the list

{ "key": "X-Frame-Options", "value": "SAMEORIGIN" }

SAMEORIGIN lets only your own pages frame the site. DENY refuses every frame.

Source: Vercel docs: vercel.json headers

X-Content-Type-Options

Keep X-Content-Type-Options with the value nosniff in the list, as the file above and the example from Vercel both do.

vercel.json, inside the list

{ "key": "X-Content-Type-Options", "value": "nosniff" }

Source: Vercel docs: vercel.json headers

Referrer-Policy

Add Referrer-Policy to the list.

vercel.json, inside the list

{ "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }

Source: Vercel docs: vercel.json headers

Permissions-Policy

Add Permissions-Policy to the list.

vercel.json, inside the list

{ "key": "Permissions-Policy", "value": "camera=(), microphone=(), geolocation=()" }

Each feature with an empty list () is switched off for every origin. Name the features the site does not use.

Source: Vercel docs: vercel.json headers

How to check it

After the next deploy, read the headers the live site sends with curl -I https://www.example.com/ or in the network panel of your browser developer tools. The free check gives an A to F grade and shows how to fix the first two findings in a few seconds, with no sign-up. Run the free check.

More on each header: how to fix a missing HSTS header, how to fix a missing Content-Security-Policy header, how to fix a missing X-Frame-Options header and the security headers guide.

The same headers on other platforms: Netlify, WordPress and Webflow.