Pipeline

The pageflare pipeline transforms a directory of static assets into an optimized output in four ordered phases: discover, analyze, process, and write. Understanding each phase helps you reason about ordering dependencies and what happens when something goes wrong.

The four phases

1. Discover

The pipeline walks the input directory and builds a list of candidate files. Files are filtered by extension — pageflare only considers file types it knows how to handle (.html, .css, .js, .mjs, .svg, .png, .jpg, .jpeg, .webp, .gif, .avif, .woff, .woff2, .ttf, .otf). Unrecognized file types are carried through to the output unchanged.

2. Analyze

Before any transformation runs, every file is read and registered in the asset graph. During analysis:

HTML files are parsed to find all referenced assets (images, stylesheets, scripts, fonts).
CSS files are scanned for url() and @import references.
JS files are inspected for dynamic import() and fetch() calls where resolvable.

This produces the full dependency graph that later phases rely on. For example, the resource hint processor needs to know which fonts an HTML file references before it can generate <link rel="preload"> tags.

3. Process

Processing is where transformations happen. For each file, the pipeline looks up which processors are active for that file type and runs them in order.

Files are processed concurrently across available CPU cores, making pageflare fast even on large sites with hundreds of assets. Processors within a single file run sequentially — a file’s processor chain is ordered and deterministic.

The output of each processor becomes the input for the next processor in the chain. If a processor produces no change, it passes the original content to the next processor unchanged.

4. Write

After all processors have run, each output file is written to the output directory. The output path mirrors the input directory structure. When content hashing is enabled, filenames are updated at write time and all references in HTML, CSS, and JS are rewritten to the new paths before the files are saved.

If the output directory is the same as the input (in-place mode), files are written atomically — using a temporary path then renamed — to minimize the window where a partially-written file could be served.

Configuration and feature gating

Which optimizations are active depends on the pageflare.jsonc config. Each feature flag enables one or more processors. Pro-gated features are silently excluded if no valid license is present — they do not produce errors, they simply do not run.

Error handling

Errors are file-scoped. If a processor fails on one file, that file is marked as errored and skipped in the write phase, but the rest of the pipeline continues. The final summary reports error counts alongside optimized and unchanged counts.

Processors — how individual transformations are structured
Asset Graph — the dependency tracking layer built during analyze