headers()

headers?(): Promise<Header[]> | Header[]

type Header = {
  source: string
  headers: { key: string; value: string }[]
  basePath?: false
  locale?: false
  has?: RouteHas[]
  missing?: RouteHas[]
}

This is where a whole-site security baseline lives — HSTS, X-Content-Type-Options, Referrer-Policy, Permissions-Policy — plus per-path exceptions like CORS on /api/:path*. Headers are evaluated first in the routing chain, before redirects, proxy and the filesystem.

When to reach for it

• Applying a static security header set across every response.
• Opening CORS for Route Handlers consumed by another origin.
• Setting Cache-Control on your own static assets in public/.

What trips people up

Files under /_next/static carry a content hash and are pinned to public, max-age=31536000, immutable; you cannot override their Cache-Control here, and attempts to do so are silently ignored. Overriding within your own config works the opposite way to CSS specificity: when two matching entries set the same key, the last one wins, so put broad defaults first and narrow overrides after. A CSP with a nonce cannot be expressed here at all, because these values are static per build — that belongs in proxy.ts. Note that it is /(.*) that stops being a universal matcher once locales are configured: it is converted to /(en|fr|de)/(.*) and so will not match the top-level / or /fr routes that /:path* would still match.

import type { NextConfig } from 'next'

const securityHeaders = [
  {
    key: 'Strict-Transport-Security',
    value: 'max-age=63072000; includeSubDomains; preload',
  },
  { key: 'X-Content-Type-Options', value: 'nosniff' },
  { key: 'X-Frame-Options', value: 'SAMEORIGIN' },
  { key: 'Referrer-Policy', value: 'origin-when-cross-origin' },
  {
    key: 'Permissions-Policy',
    value: 'camera=(), microphone=(), geolocation=(), browsing-topics=()',
  },
]

const nextConfig: NextConfig = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: securityHeaders,
      },
    ]
  },
}

export default nextConfig

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  async headers() {
    return [
      {
        source: '/api/:path*',
        headers: [
          { key: 'Access-Control-Allow-Origin', value: 'https://acme.com' },
          {
            key: 'Access-Control-Allow-Methods',
            value: 'GET, POST, PUT, DELETE, OPTIONS',
          },
          {
            key: 'Access-Control-Allow-Headers',
            value: 'Content-Type, Authorization',
          },
        ],
      },
    ]
  },
}

export default nextConfig

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [{ key: 'x-hello', value: 'there' }],
      },
      {
        source: '/hello',
        headers: [{ key: 'x-hello', value: 'world' }],
      },
    ]
  },
}

export default nextConfig