JavaScript Processors

pageflare applies two transformations to JavaScript: minification to reduce file size, and deferral to prevent scripts from blocking the browser’s HTML parser.

JS minification

pageflare’s JavaScript minifier operates on the full parsed structure of your scripts rather than performing text-level substitutions, enabling semantically safe transformations:

Identifier shortening — local variable and function names are replaced with the shortest possible names (longVariableName → a).
Dead code elimination — unreachable branches (e.g. if (false) { ... }) and unused function declarations are removed.
Constant folding — expressions with known values are evaluated at build time (2 * 1024 → 2048).
Whitespace and comment removal — all non-significant whitespace and comments are stripped.
String literal compression — quote style is normalized to whichever is shorter.

Sourcemaps

pageflare does not generate or update sourcemaps during minification. If your build toolchain produces sourcemaps, they will be copied to the output directory unchanged alongside the minified files. Browser devtools will attempt to use them but the line/column mappings will be incorrect after minification. For production deployments this is usually acceptable — sourcemaps are used for debugging, not for end-user performance.

Script deferral

Render-blocking scripts are <script> tags in the <head> (or early <body>) without async or defer. The browser must download, parse, and execute them before it can continue parsing the HTML. This delays Time to First Byte (TTFB) → First Contentful Paint (FCP) → Largest Contentful Paint (LCP) on every page load.

Script deferral is implemented in the HTML processor layer — it modifies the HTML rather than the JavaScript files themselves. Two strategies are available:

`defer` method

Adds the defer attribute to qualifying <script src="..."> tags:

<!-- Before -->
<script src="/analytics.js"></script>

<!-- After -->
<script src="/analytics.js" defer></script>

defer scripts are downloaded in parallel with HTML parsing and executed in order after the document is fully parsed, just before DOMContentLoaded. This preserves script execution order while eliminating the parsing block.

`user-interaction` method

Scripts are not loaded at all until the user interacts with the page. The first interaction event (mouse move, scroll, keydown, or touch) triggers injection of all deferred scripts as dynamic <script> elements.

This is appropriate for scripts that have no effect before interaction — chat widgets, feedback buttons, non-critical analytics. It is not appropriate for scripts that must run before the user can interact (e.g. a form validation library).

{
  "js_defer": true,
  "js_defer_method": "user-interaction",
  "js_defer_excludes": ["stripe.js", "recaptcha"]
}

What qualifies for deferral

Only external scripts (<script src="...">) without an existing async or defer attribute are candidates. Inline scripts are never deferred — their execution timing is defined by their position in the document and changing it would risk breaking page behavior.

HTML processors — where script deferral is implemented
Processors — how the JS processor chain is ordered
Pipeline — the processing pipeline that runs JS transformations