Processors

A processor is the fundamental unit of transformation in pageflare. Each processor is a self-contained component that:

1. Declares which file types it handles.
2. Receives the current content of a file.
3. Returns the transformed content (or the original content if no change is needed).

Processors are stateless with respect to individual files. They may read the shared asset graph (built during the analyze phase) but do not modify it.

How processors are selected

At startup, pageflare assembles an ordered list of active processors for each file category based on the resolved configuration:

• Feature flags that are true contribute their processor(s) to the active set.
• Feature flags that are false or absent contribute nothing.
• Pro-gated features are silently excluded if no valid license is present.

Once assembled, the active set is fixed for the duration of the run. Every file of a given type receives the exact same sequence of transformations.

Processor chaining

Multiple processors can act on a single file. They run in a defined order — the output of one processor becomes the input of the next.

For an HTML file with a typical Free-tier config, the chain might look like:

HTML file
  → LazyLoadProcessor       (adds loading="lazy" to images)
  → ScriptDeferProcessor    (adds defer to scripts)
  → ResourceHintProcessor   (injects preload/preconnect links)
  → HtmlMinifyProcessor     (minifies the result)

Minification runs last so it compresses the output of all earlier processors rather than content that might subsequently be modified.

Note

The ordering within the chain is fixed and deterministic, not driven by config file order. If you enable both lazy_load_images and minify_html, lazy loading always runs before minification regardless of how they appear in pageflare.jsonc.

File-type matching

Each processor declares the set of file categories it handles. The pipeline looks up all active processors that match the current file’s category and runs them in order.

Category	Processors that can match
HTML	Lazy load, script defer, resource hints, critical CSS injection, HTML minify, YouTube facades, WP bloat removal, SPA mode
CSS	CSS minify, critical CSS extraction
JavaScript	JS minify, script deferral
Image	Size detection, adaptive sizing
Font	Font preloading, font-display

Tier gating

Each processor is either Free or Pro. Pro processors are excluded at startup when no valid license is present. There is no per-file license check — the decision is made once when the active set is assembled.

Pro-only processors cover features that require significant compute or deliver the largest gains on high-traffic sites:

Feature	Tier
Critical CSS extraction and injection	PRO
YouTube facades	PRO
WordPress bloat removal	PRO
SPA mode with View Transitions	PRO
Google Fonts self-hosting	PRO
Unicode-range subsetting	PRO
Adaptive image sizing (srcset)	PRO
Filename hashing	PRO
Speculation rules	PRO

Mental model

Think of the processor setup as a pipeline template stamped out at startup. Every file of a given type gets the exact same sequence of transformations. There is no conditional logic inside the pipeline loop — all decisions about which processors are active were made before processing began.

Related concepts

• Pipeline — the four phases that drive processor execution
• HTML processors — what each HTML processor does
• CSS processors — CSS minification and critical CSS
• JavaScript processors — JS minification and script deferral
• Image processors — size detection and adaptive sizing
• Font processors — preloading, font-display, and self-hosting