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 pageflare init to generate a fully-commented config file with every option set to its default value:

pageflare init
pageflare init dist/

This writes pageflare.jsonc in the target directory. 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)
`image_cdn`	string	`"optimize"`	Control CDN image optimization behavior: `"optimize"` or `"off"`

{
  "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_subset`	boolean	`true`	PRO Subset font files to only include characters used on the site, then re-encode as WOFF2

{
  "font_display_swap": true,

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

Analytics Self-Hosting

Download and self-host third-party analytics scripts to eliminate external requests.

Option	Type	Default	Description
`self_host_analytics`	boolean	`false`	PRO Download and self-host analytics scripts (Google Analytics, Plausible, Fathom, Umami, Matomo)
`analytics_minimal`	boolean	`false`	PRO Strip unnecessary tracking features from analytics scripts to reduce size
`analytics_cookieless`	boolean	`false`	PRO Remove cookie-based tracking for GDPR compliance
`analytics_randomize_id`	boolean	`false`	PRO Randomize analytics client IDs for enhanced privacy
`analytics_adblocker_detect`	boolean	`false`	PRO Enable fallback when analytics is blocked by adblockers

{
  // Pro features
  "self_host_analytics": true,
  "analytics_minimal": false,
  "analytics_cookieless": false,
  "analytics_randomize_id": false,
  "analytics_adblocker_detect": false
}

SVG Optimization

Option	Type	Default	Description
`optimize_svg`	boolean	`true`	Optimize inline SVGs — remove editor metadata, comments, and redundant attributes

{
  "optimize_svg": true
}

Image Optimization

Build-time image optimization with format conversion and responsive variants.

Option	Type	Default	Description
`optimize_images`	boolean	`true`	PRO Generate optimized image variants at build time
`image_formats`	string[]	`["webp"]`	Target formats for conversion (e.g., `["webp", "avif"]`)
`image_widths`	number[]	`[320, 640, 960, 1280, 1920]`	Breakpoint widths for responsive srcset generation
`image_quality`	number	`80`	Encoding quality (1–100) for lossy formats

{
  // Pro features
  "optimize_images": true,
  "image_formats": ["webp"],
  "image_widths": [320, 640, 960, 1280, 1920],
  "image_quality": 80
}

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
}

Platform

Option	Type	Default	Description
`platform`	string	`"auto"`	Deployment platform: `"auto"`, `"vercel"`, `"netlify"`, `"cloudflare-pages"`, or `"none"`

{
  "platform": "auto"
}

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
`wp_hide_paths`	boolean	`true`	PRO Sanitize WordPress paths in static exports: rename `wp-content` → `content`, `wp-includes` → `includes`, remove `wp-admin`
`partytown`	boolean	`false`	PRO Offload third-party scripts to a Web Worker using Partytown
`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
  "wp_hide_paths": true,
  "partytown": false,
  "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,
  "optimize_images": true,           // Pro
  "image_formats": ["webp"],         // Pro
  "image_widths": [320, 640, 960, 1280, 1920],  // Pro
  "image_quality": 80,               // Pro

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

  // ── Analytics ─────────────────────────────────────────────
  "self_host_analytics": false,      // Pro
  "analytics_minimal": false,        // Pro
  "analytics_cookieless": false,     // Pro
  "analytics_randomize_id": false,   // Pro
  "analytics_adblocker_detect": false, // Pro

  // ── SVG ───────────────────────────────────────────────────
  "optimize_svg": true,

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

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

  // ── Platform ──────────────────────────────────────────────
  "platform": "auto",

  // ── Other ─────────────────────────────────────────────────
  "defer_background_images": true,   // Pro
  "youtube_facades": true,           // Pro
  "remove_wp_bloat": true,           // Pro
  "wp_hide_paths": true,             // Pro
  "partytown": false,                // Pro
  "hash_filenames": true,            // Pro

  // ── Sitemap ───────────────────────────────────────────────
  "sitemap": {
    "enabled": null,
    "base_url": null,
    "changefreq": "weekly",
    "priority": 0.5,
    "exclude": ["404.html"]
  },

  // ── LLM Files ─────────────────────────────────────────────
  "llm": {
    "enabled": null,
    "theme": "structured",
    "base_url": null,
    "site_name": null,
    "sub_indexes": [],
    "robots_policy": "allow-all",
    "content_signals": {}
  }
}

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

Sitemap

Automatic sitemap.xml generation with lastmod dates and gzip compression.

Option	Type	Default	Description
`sitemap.enabled`	boolean/null	`null`	Enable sitemap generation (`null` = auto, based on tier)
`sitemap.base_url`	string/null	`null`	Base URL for the site (e.g., `"https://example.com"`) — required for absolute URLs
`sitemap.changefreq`	string	`"weekly"`	Default change frequency: `"always"`, `"hourly"`, `"daily"`, `"weekly"`, `"monthly"`, `"yearly"`, `"never"`
`sitemap.priority`	number	`0.5`	Default priority for pages (0.0 to 1.0)
`sitemap.include`	string[]	`[]`	Glob patterns to include (empty = all pages)
`sitemap.exclude`	string[]	`["404.html"]`	Glob patterns to exclude

{
  "sitemap": {
    "enabled": null,
    "base_url": "https://example.com",
    "changefreq": "weekly",
    "priority": 0.5,
    "include": [],
    "exclude": ["404.html"]
  }
}

LLM Files

Control generation of llms.txt files for LLM-friendly site indexing.

Option	Type	Default	Description
`llm.enabled`	boolean/null	`null`	Enable llms.txt generation (`null` = auto, based on tier)
`llm.theme`	string	`"structured"`	Output theme for llms.txt
`llm.base_url`	string/null	`null`	Base URL prepended to paths
`llm.site_name`	string/null	`null`	Site name for the llms.txt header
`llm.sub_indexes`	string[]	`[]`	Folder prefixes that get their own llms.txt (e.g., `["docs", "api"]`)
`llm.robots_policy`	string	`"allow-all"`	Robots.txt policy preset: `"allow-all"`, `"block-ai-training"`, `"block-all-ai"`, `"block-all"`
`llm.content_signals`	object	`{}`	Per-signal overrides: `{ "search": "yes"/"no", "ai_input": "yes"/"no", "ai_train": "yes"/"no" }`

{
  "llm": {
    "enabled": null,
    "theme": "structured",
    "base_url": null,
    "site_name": null,
    "sub_indexes": [],
    "robots_policy": "allow-all",
    "content_signals": {}
  }
}