How to Set Up the next.config.js headers() Array

This guide is part of the Vercel & Next.js Security Header Management reference. It covers the precise syntax of the next.config.js headers() async function — the build-time mechanism for emitting static security headers like HSTS and Content-Security-Policy — and the route-matching, App-vs-Pages, and static-asset edge cases that cause it to silently misfire.

Configuration Syntax & Exact Values

headers() is an async export that returns an array. Each element is an object with a source (a Next.js path pattern, not raw regex) and a headers array of { key, value } objects. The function runs at build time, so every value must be a static string — it cannot read the request and cannot mint a per-request nonce.

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        // source: Next.js path-matching syntax. '/(.*)' matches every route.
        source: '/(.*)',
        headers: [
          // 1 year. includeSubDomains extends the policy to every subdomain.
          { key: 'Strict-Transport-Security', value: 'max-age=31536000; includeSubDomains' },
          // nosniff: forces strict MIME checking, blocking content-sniffing attacks.
          { key: 'X-Content-Type-Options', value: 'nosniff' },
          // DENY: page may not be framed anywhere; legacy clickjacking control.
          { key: 'X-Frame-Options', value: 'DENY' },
          // Send only the origin on cross-origin navigations.
          { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
        ],
      },
    ];
  },
};

Annotated breakdown of each field:

• source — a path pattern in Next.js syntax. /(.*) is a named-free wildcard matching all paths. Named parameters (/:path*) and the negative form are supported; raw JavaScript RegExp objects are not.
• key — the exact header name. Casing is normalized to lowercase on the wire; write it conventionally for readability.
• value — a static string only. There is no always flag as in Nginx or Apache, because Next.js emits these headers on every response it generates for matching routes, error pages included — the equivalent guarantee is built in.

To scope headers to a subset of routes, add more objects with narrower source patterns. More-specific entries do not override broader ones; all matching entries apply, so overlapping source patterns that set the same key produce duplicates.

// next.config.js — route-scoped headers
module.exports = {
  async headers() {
    return [
      {
        source: '/api/(.*)',
        headers: [
          { key: 'Content-Security-Policy', value: "default-src 'none'; frame-ancestors 'none'" },
          { key: 'Cache-Control', value: 'no-store' },
        ],
      },
      {
        // Long-lived caching for hashed, immutable build assets.
        source: '/_next/static/(.*)',
        headers: [
          { key: 'Cache-Control', value: 'public, max-age=31536000, immutable' },
        ],
      },
    ];
  },
};

Conditional matching with has and missing

Beyond source, each entry accepts optional has and missing arrays that gate the rule on request attributes — header, cookie, query, or host. This is the only request-aware lever the config layer exposes, and it still cannot read a value into the output; it only decides whether the static entry fires. Use it to skip headers already injected by an upstream proxy or CDN, or to apply a stricter policy to a specific host in a multi-domain deployment.

// next.config.js — apply the header only when an upstream marker is absent.
{
  source: '/(.*)',
  missing: [{ type: 'header', key: 'x-skip-security-headers' }],
  headers: [
    { key: 'X-Frame-Options', value: 'SAMEORIGIN' },
  ],
},

Two further prefix rules trip people up. When basePath is set, every source is automatically prefixed with it; pass basePath: false on the entry to opt out. Likewise, with i18n routing enabled, source patterns are locale-prefixed unless you set locale: false. If a header silently fails to match on a sub-path or a localized route, an unexpected automatic prefix is the usual cause — inspect the resolved route with curl -sI before touching the pattern itself.

Server-Side Configuration

next.config.js

Place the headers() export in next.config.js (or next.config.mjs with export default). It applies to server-rendered and statically-generated routes alike, on both the App Router and the Pages Router.

// next.config.mjs (ES module form)
const nextConfig = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          { key: 'Strict-Transport-Security', value: 'max-age=63072000; includeSubDomains; preload' },
          { key: 'X-Content-Type-Options', value: 'nosniff' },
          { key: 'X-Frame-Options', value: 'DENY' },
          { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
          { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
        ],
      },
    ];
  },
};
export default nextConfig;

Note: vercel.json alternative

If the deployment is a static export (output: 'export'), headers() is dropped at build — there is no server to run it. On Vercel, move these same keys into the vercel.json headers array, which the platform router applies to every path including static files. Do not define a key in both next.config.js and vercel.json on a server-rendered build, or the response carries duplicates. The full trade-off is in the vercel.json vs next.config.js comparison.

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "Strict-Transport-Security", "value": "max-age=63072000; includeSubDomains; preload" },
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
      ]
    }
  ]
}

The choice between the three mechanisms is not a matter of taste — each has a single condition under which it is the correct home for a header. A per-request value such as a CSP nonce can never come from build-time config, so it belongs in middleware. A static export has no server to run headers(), so on Vercel it belongs in vercel.json. Everything else — the common server-rendered or hybrid build — belongs in next.config.js headers(), which is the least infrastructure to reason about.

Diagnostic & Verification Steps

headers() is evaluated only by next build and is silently ignored under next dev. Always verify against a production build. The distinction below is the single most common reason a correct config appears to “do nothing”: the header pipeline runs in one mode and not the other.

# 1. Build and start the production server.
npm run build && npm start

# 2. Inspect the raw response headers on the root route.
curl -sI http://localhost:3000/

Expected output (casing normalized to lowercase by Next.js; order may vary):

HTTP/1.1 200 OK
strict-transport-security: max-age=63072000; includeSubDomains; preload
x-content-type-options: nosniff
x-frame-options: DENY
referrer-policy: strict-origin-when-cross-origin
permissions-policy: camera=(), microphone=(), geolocation=()

Verify scoped entries on the paths they target, and confirm a security key appears exactly once:

# Route-scoped headers on an API path.
curl -sI http://localhost:3000/api/test | grep -iE 'content-security|cache-control'

# Confirm no duplicate HSTS line (expected: 1).
curl -sI http://localhost:3000/ | grep -ic 'strict-transport-security'

Static build assets are the easy blind spot: a /(.*) entry matches them, but it is worth confirming explicitly because a broken pattern fails silently there too. Pick a real hashed file from .next/static and request it:

# Resolve one built asset, then inspect its headers.
ASSET=$(find .next/static -name '*.js' | head -n1 | sed 's#.next##')
curl -sI "http://localhost:3000/_next/static${ASSET#/static}" | grep -iE 'strict-transport|cache-control'

Expected output on a correctly configured build — the immutable cache policy from the scoped entry plus the site-wide HSTS line:

strict-transport-security: max-age=63072000; includeSubDomains; preload
cache-control: public, max-age=31536000, immutable

If a header is absent, the build did not pick up the config: confirm you ran next build (not next dev), and that output: 'export' is not set.

Edge Cases, Security Implications & Safe Rollback

• source path matching is not raw regex. Symptom → fix: a header fails to apply to a route you expected → you used a JavaScript RegExp pattern. Rewrite it in Next.js path syntax (/(.*), /:slug*); raw regex is silently non-matching.
• Headers not applied to /_next/static assets. headers() only applies to routes matched by a source pattern. A single source: '/(.*)' matches application routes but you must verify static asset paths explicitly. Symptom → fix: curl -sI on a /_next/static/... URL shows no security headers → add a dedicated source: '/_next/static/(.*)' entry, or set the headers in vercel.json, which applies platform-wide.
• App Router vs Pages Router. headers() behaves identically on both routers — it is config-level, not request-level. The difference appears only with CSP nonces, which next.config.js cannot produce on either router; per-request nonces require middleware regardless of which router the app uses.
• Safe rollback. Headers are non-destructive, but an over-strict CSP can blank the page. To roll back: comment out the offending entry in headers(), run rm -rf .next to purge the stale build cache, then npm run build && npm start to confirm the baseline response. Re-introduce strict directives one at a time, validating with curl -sI after each.

Frequently Asked Questions

Why are my headers ignored when I run the dev server?

next dev does not evaluate the headers() export. Only next build does. Verify with npm run build && npm start or on a deployed preview.

Can I put a CSP nonce in the headers() array?

No. headers() runs at build time with no access to the request, so every value is a static string. Per-request nonces must be set in middleware. See Setting CSP with nonces in Next.js middleware.

Why do two source patterns produce duplicate headers?

All matching source entries apply — more-specific patterns do not override broader ones. If two entries set the same key for a route, the response carries both. Scope your patterns so each key is set once per route.

Does headers() work the same on the App Router and Pages Router?

Yes. headers() is config-level and router-agnostic. The only relevant difference is that neither router can generate CSP nonces from config — that requires middleware.

Conclusion

Use the headers() array for static, route-scoped security headers that need no per-request context, and validate every change against a production build (next build && next start) since next dev ignores the export entirely. Roll out incrementally: stage with a short Strict-Transport-Security max-age, confirm the headers on a preview deploy with curl -sI, then promote to full production values. For anything per-request, move to middleware.

Related

• Vercel & Next.js Security Header Management
• vercel.json vs next.config.js for headers
• Setting CSP with nonces in Next.js middleware
• HTTP Strict Transport Security deep dive