cfpages-early-hints

Generate Cloudflare Pages _headers with per-page Early Hints from your site's HTML.

Requires Node.js 22.17 or later. Currently supports Next.js static exports (output: 'export').

Usage

Install in your project:

npm install --save-dev cfpages-early-hints

Run cfpages-early-hints generate after your site's build. For Next.js, update your package.json build script:

{
  "scripts": {
    "build": "next build && cfpages-early-hints generate"
  }
}

The Next.js adapter reads out/ and writes out/_headers. Deploy out/ to Cloudflare Pages.

Options

cfpages-early-hints generate [directory] [options]

| Argument or option | Description | Default | | --- | --- | --- | | [directory] | Project root | Current directory | | --framework <framework> | Select a framework explicitly; currently accepts next | Auto-detect | | --max-html-bytes <bytes> | Maximum bytes scanned per HTML file; 0 scans the full document | 65536 (64 KiB) |

Image preloads require fetchpriority="high"; responsive preloads using imagesrcset are skipped. The CLI warns if hints are omitted to fit Cloudflare's header limits.

Custom headers

Place your custom _headers file in your framework's static assets directory so it is copied to the root of the build output:

/*
  X-Frame-Options: DENY

The CLI preserves custom headers and replaces its previous generated hints. Keep manual edits outside the generated comment sections.