Cloudflare Pages

Cloudflare Pages runs your build command in a managed environment and then deploys the output. Pageflare slots in as a post-build step: your framework builds the site, then pageflare optimizes the output before Pages uploads it.

How It Works

Cloudflare Pages gives you a single Build command field. Chain your normal build command with pageflare using &&:

npm run build && pageflare dist/ --in-place --no-progress

Pages runs this command, pageflare rewrites the files in dist/, and Pages deploys the optimized result. No extra build plugins or wrangler config needed.

Step 1 — Add Your License as a Secret

Pro features require your license key. Store it as an environment variable in the Pages project settings so it is never committed to source control.

1. Open your Pages project in the Cloudflare dashboard.
2. Go to Settings > Environment variables.
3. Click Add variable, set the name to PAGEFLARE_LICENSE, paste your key, and toggle Encrypt on.
4. Save. The variable is injected into every build — both production and preview deployments.

Tip

If you only want Pro optimizations on production (not preview branches), set the variable under the Production environment only, and leave Preview empty or set it to a free-tier value.

Step 2 — Set the Build Command

In Settings > Builds & deployments > Build settings, update the Build command field:

npm run build && pageflare dist/ --in-place --no-progress

Replace npm run build and dist/ with your actual build command and output directory. Common examples:

Framework	Build command
Astro	npm run build && pageflare dist/ --in-place --no-progress
Next.js (static export)	npm run build && pageflare out/ --in-place --no-progress
Hugo	hugo && pageflare public/ --in-place --no-progress
Eleventy	npx @11ty/eleventy && pageflare _site/ --in-place --no-progress
Jekyll	jekyll build && pageflare _site/ --in-place --no-progress

Note

Cloudflare Pages build environments include Node.js but not pageflare by default. The npm install -g @pageflare/cli step is required if you are not using a package.json-based install. See Step 3.

Step 3 — Install pageflare in the Build Environment

Option A: Install globally via npm (recommended for Pages)

Prefix your build command with the install step:

npm install -g @pageflare/cli && npm run build && pageflare dist/ --in-place --no-progress

Option B: Add as a dev dependency

Add pageflare to your project so Pages installs it automatically via npm ci:

npm install --save-dev @pageflare/cli

Then reference it via npx or add a script to package.json:

package.json

{
  "scripts": {
    "build": "astro build",
    "build:optimized": "astro build && pageflare dist/ --in-place --no-progress"
  }
}

Set the Pages build command to npm run build:optimized.

Option C: curl installer

curl -fsSL https://get.appz.dev/pageflare/install.sh | sh && npm run build && pageflare dist/ --in-place --no-progress

Step 4 — Verify in Preview Deployments

Every pull request gets a preview deployment. Check the build log to confirm pageflare ran:

1. Open the deployment in the Cloudflare dashboard.
2. Click View build log.
3. Look for the pageflare summary output near the end:

  Done  145.2 KB saved (38.1%)  1.2s
  Files  42 total, 38 optimized, 4 unchanged, 0 errors

If you see a license error on preview but not production, check that PAGEFLARE_LICENSE is set for the Preview environment as well.

Full Build Command Example

npm install -g @pageflare/cli && npm run build && pageflare dist/ --in-place --no-progress

With a pageflare.jsonc config in your repo root, pageflare picks it up automatically — no extra flags needed.

Configuration File

Place pageflare.jsonc in the repository root:

pageflare.jsonc

{
  // Optimization settings
  "minify_html": true,
  "minify_css": true,
  "minify_js": true,
  "js_defer": true,
  "lazy_images": true,
  "img_dimensions": true,
  "font_swap": true
}

See the Configuration reference for the full list of options.

Troubleshooting

Build fails with pageflare: command not found The install step ran but the binary is not on PATH. Use npx pageflare or ensure the install script’s target directory (~/.local/bin or /usr/local/bin) is on the PATH before calling pageflare.

License not detected Confirm the environment variable name is exactly PAGEFLARE_LICENSE (all caps) and that the variable is saved for the correct environment (Production / Preview).

Output directory mismatch If pageflare reports zero files processed, the directory path in the command does not match your framework’s actual output. Check your framework’s config for the output directory name.