Configuration

Pageflare is configured through a pageflare.jsonc file in your input directory. All options have sensible defaults — the config file is optional unless you want to customize behavior.

Generating the Config File

Run --init to generate a fully-commented config file with every option set to its default value:

pageflare dist/ --init

This writes dist/pageflare.jsonc. Edit it to suit your site.

File Format

The file uses JSONC (JSON with comments). You can use // and /* */ comments freely:

{
  // Minification
  "minify_html": true,
  "minify_css": true,
  "minify_js": true
}

Default Location

Pageflare looks for the config file at <input>/pageflare.jsonc. To use a different path, pass -c / --config:

pageflare dist/ --config ./config/pageflare.jsonc

All Configuration Options

Minification

Control whether HTML, CSS, and JavaScript are minified.

Option	Type	Default	Description
minify_html	boolean	true	Minify HTML files — collapse whitespace, remove optional tags and comments
minify_css	boolean	true	Minify CSS — remove whitespace, shorten values, deduplicate rules
minify_js	boolean	true	Minify JavaScript — remove whitespace, shorten identifiers, tree-shake dead code

{
  "minify_html": true,
  "minify_css": true,
  "minify_js": true
}

---

JavaScript Loading

Control how JavaScript is deferred to improve initial page load.

Option	Type	Default	Description
js_defer	boolean	true	Defer non-critical JavaScript until after the page is interactive
js_defer_method	string	"user-interaction"	When to load deferred scripts: "user-interaction" (first scroll/click/keypress) or "defer" (standard HTML defer)
js_defer_excludes	string[]	[]	Array of script URL patterns to exclude from deferral (substring match)
js_defer_timeout	number	10000	Fallback timeout in milliseconds — deferred scripts load after this delay even without user interaction

{
  "js_defer": true,
  "js_defer_method": "user-interaction",
  "js_defer_excludes": [
    "analytics.js",
    "/critical/"
  ],
  "js_defer_timeout": 10000
}

js_defer_method values:

• "user-interaction" — Scripts load on the first user interaction (scroll, click, or keypress), with js_defer_timeout as a fallback. This maximizes Time to Interactive (TTI) improvement.
• "defer" — Uses the standard HTML defer attribute. Scripts run after the document is parsed but do not wait for user interaction.

js_defer_excludes accepts partial URL strings. Any script whose src contains a listed substring is excluded from deferral:

{
  "js_defer_excludes": [
    "stripe.js",      // Payment scripts that must load immediately
    "/vendor/init"    // Initialisation scripts required on first paint
  ]
}

---

Images

Control lazy loading and automatic dimension injection for images and iframes.

Option	Type	Default	Description
lazy_load_images	boolean	true	Add loading="lazy" to images below the fold
lazy_load_iframes	boolean	true	Add loading="lazy" to iframes
lazy_load_excludes	string[]	[]	Array of image URL patterns to exclude from lazy loading
add_image_dimensions	boolean	true	Detect and inject width and height attributes on <img> tags that are missing them, preventing layout shift (CLS)

{
  "lazy_load_images": true,
  "lazy_load_iframes": true,
  "lazy_load_excludes": [
    "logo.png",
    "/hero/"
  ],
  "add_image_dimensions": true
}

Images near the top of the page (above the fold) are automatically excluded from lazy loading regardless of lazy_load_excludes.

---

Fonts

Option	Type	Default	Description
font_display_swap	boolean	true	Inject font-display: swap into @font-face rules so text remains visible while custom fonts load
self_host_google_fonts	boolean	true	PRO Download Google Fonts and serve them from your own domain, eliminating the third-party DNS lookup
font_unicode_range	boolean	true	PRO Generate unicode-range descriptors for self-hosted fonts to avoid loading character sets not used on the page

{
  "font_display_swap": true,

  // Pro features
  "self_host_google_fonts": true,
  "font_unicode_range": true
}

---

Performance Hints

Option	Type	Default	Description
preconnect_hints	boolean	true	Inject <link rel="preconnect"> for third-party origins detected in the page, reducing connection latency
speculation_rules	boolean	true	PRO Inject the Speculation Rules API to prerender likely-next pages in supporting browsers
spa_mode	boolean	true	PRO Enable single-page app navigation using the View Transitions API for instant client-side page changes

{
  "preconnect_hints": true,

  // Pro features
  "speculation_rules": true,
  "spa_mode": true
}

---

CSS

Option	Type	Default	Description
critical_css	boolean	true	PRO Extract and inline above-the-fold CSS, then load the full stylesheet asynchronously to eliminate render-blocking CSS

{
  // Pro feature
  "critical_css": true
}

---

Other Optimizations

Option	Type	Default	Description
defer_background_images	boolean	true	PRO Defer off-screen CSS background images using IntersectionObserver
youtube_facades	boolean	true	PRO Replace YouTube embeds with lightweight click-to-load facades, eliminating ~500 KB of third-party JavaScript on initial load
remove_wp_bloat	boolean	true	PRO Remove WordPress-specific bloat: emoji scripts, redundant meta tags, and unused query strings
platform_images	boolean	true	PRO Convert images to next-gen formats (WebP/AVIF) and generate responsive srcset attributes
hash_filenames	boolean	true	PRO Append content hashes to asset filenames for long-term cache control, then update all references in HTML and CSS

{
  // Pro features
  "defer_background_images": true,
  "youtube_facades": true,
  "remove_wp_bloat": false,  // Disable if not a WordPress site
  "platform_images": true,
  "hash_filenames": true
}

---

Full Example Config

A config file with all options explicit (as generated by pageflare --init):

{
  // ── Minification ─────────────────────────────────────────
  "minify_html": true,
  "minify_css": true,
  "minify_js": true,

  // ── JavaScript Loading ────────────────────────────────────
  "js_defer": true,
  "js_defer_method": "user-interaction",
  "js_defer_excludes": [],
  "js_defer_timeout": 10000,

  // ── Images ────────────────────────────────────────────────
  "lazy_load_images": true,
  "lazy_load_iframes": true,
  "lazy_load_excludes": [],
  "add_image_dimensions": true,

  // ── Fonts ─────────────────────────────────────────────────
  "font_display_swap": true,
  "self_host_google_fonts": true,   // Pro
  "font_unicode_range": true,        // Pro

  // ── Performance Hints ─────────────────────────────────────
  "preconnect_hints": true,
  "speculation_rules": true,         // Pro
  "spa_mode": true,                  // Pro

  // ── CSS ───────────────────────────────────────────────────
  "critical_css": true,              // Pro

  // ── Other ─────────────────────────────────────────────────
  "defer_background_images": true,   // Pro
  "youtube_facades": true,           // Pro
  "remove_wp_bloat": true,           // Pro
  "platform_images": true,           // Pro
  "hash_filenames": true             // Pro
}

Pro-only options are silently ignored on the Free tier — you can leave them set to true in your config without causing errors.