First Optimization

This guide walks through a real pageflare run in detail: what the output means, how to use JSON mode for scripting, and how to create and tune a config file.

Prerequisites

• pageflare installed — see the Installation guide.
• Node.js 20+ (only needed if you installed via npm).
• A built static site. If you don’t have one yet, any directory of HTML files works.

1. Build your site

Run your site generator’s build command so there is a directory of static files ready to process:

npm run build     # produces dist/ for most JS-based tools

For this walkthrough, assume the output directory is dist/.

2. Run pageflare

pageflare dist/

Without --output, pageflare writes results to dist/.appz. This leaves your original dist/ intact so you can compare before and after.

pageflare dist/

  pageflare  → dist/.appz

Done  145.2 KB saved (38.1%)  1.2s
Files  42 total, 38 optimized, 4 unchanged, 0 errors
Size  381 KB → 235 KB
Features
  ✓ minify_html  ✓ minify_css  ✓ minify_js  ✓ js_defer  ✓ lazy_images  ✓ img_dimensions
  ✓ font_swap  ✗ self_host_fonts  ✗ critical_css  ✗ youtube_facades

Reading the output

Done line — shows total bytes saved (absolute and percentage) and wall-clock time.

Files line — 42 total means 42 files were found in the input. 38 optimized had at least one optimization applied. 4 unchanged were already optimal or are file types pageflare does not modify (e.g. images, PDFs). 0 errors means nothing failed.

Size line — aggregate payload before and after across all optimized files.

Features line — each optimization that pageflare attempted is listed. ✓ means it ran successfully. ✗ means it was skipped (disabled in config, no matching content found, or a Pro-only feature that requires a license).

3. Optimize in place

When you are ready to deploy the optimized files, use --output pointing to the same directory as the input, or use --in-place:

# Write results back to dist/
pageflare dist/ --output dist/

# Equivalent shorthand
pageflare dist/ --in-place

Caution

--in-place overwrites your build output. Make sure your build step runs before pageflare in your pipeline so you can always regenerate from source.

4. Use --json for programmatic output

In CI pipelines or scripts you may want to parse the results. The --json flag writes structured output to stdout:

pageflare dist/ --json

pageflare dist/ --json

{
"version": "1.0.0",
"input": "dist/",
"output": "dist/.appz",
"duration_ms": 1184,
"files": {
  "total": 42,
  "optimized": 38,
  "unchanged": 4,
  "errors": 0
},
"bytes_before": 390144,
"bytes_after": 240640,
"bytes_saved": 149504,
"features_applied": [
  "minify_html", "minify_css", "minify_js",
  "js_defer", "lazy_load_images", "add_image_dimensions",
  "font_display_swap", "preconnect_hints"
]
}

You can pipe this into jq to extract specific values — for example, to fail a CI step if less than 20% was saved:

SAVED=$(pageflare dist/ --json | jq '.bytes_saved / .bytes_before')
echo "Saved: $SAVED"

5. Create a config file

Running pageflare --init generates a pageflare.jsonc config file in the current directory with every option listed and commented:

pageflare --init

pageflare --init

  Created pageflare.jsonc

The generated file looks like this:

{
  // pageflare.jsonc — configuration for pageflare CLI

  "minify_html": true,
  "minify_css": true,
  "minify_js": true,
  "js_defer": true,
  "lazy_load_images": true,
  "lazy_load_iframes": true,
  "add_image_dimensions": true,
  "font_display_swap": true,
  "preconnect_hints": true

  // Pro features — require an active Pro license
  // "self_host_google_fonts": true,
  // "font_unicode_range": true,
  // "critical_css": true,
  // "defer_background_images": true,
  // "spa_mode": true,
  // "speculation_rules": true,
  // "youtube_facades": true,
  // "remove_wp_bloat": true,
  // "platform_images": true,
  // "hash_filenames": true
}

To disable a feature, set it to false. To enable a Pro feature, uncomment it and ensure you have activated your license (see License activation).

6. Use the config file

Pageflare automatically picks up pageflare.jsonc in the current directory. To specify a different path use --config:

pageflare dist/ --config path/to/pageflare.jsonc

7. Force reprocessing

Pageflare caches processed files to avoid redundant work. If you need to force a full reprocess — for example after updating the config — use --force:

pageflare dist/ --force

Next steps

• CLI Commands reference — every flag explained.
• Configuration reference — full config file documentation.
• CI/CD integration — run pageflare in GitHub Actions, GitLab CI, and more.
• Platform Guides — deployment-specific integration instructions.