tools/rendering/precompilation/ — ParseResult precompilation · @awacloud/fw

Purpose

Walks one or more .html template files, runs them through parser.fromHTML() at build time, and emits the resulting ParseResult as JSON. The runtime can then load the precompiled artefact directly and pass it to template.fromParseResult(json), saving the per-template parsing cost at first paint.

CLI usage

bun tools/rendering/precompilation/ <input> [options]

Argument / flag	Description
`<input>`	A `.html` file OR a directory (recursive walk).
`--out <dir>`	Output directory. Default: alongside each input file.
`--ext <ext>`	Output extension. Default `.parseresult.json`.
`--glob <pattern>`	Glob filter when `<input>` is a directory. Default `*/.html`.
`--minify`	Strips whitespace from the emitted JSON.
`--verify`	Re-instantiates via `template.fromParseResult` and deep-compares.
`--esm`	Also emits a sibling `.js` file: `export default {...}`.

Via the npm script:

bun run build:parseresult my-templates/ --out dist/parseresult --minify --esm

Example

Input — nav.html:

<nav class="main"><h1>#{title}</h1></nav>

Output — nav.html.parseresult.json:

{"template":[...],"iterates":{...}}

With --esm, sibling nav.html.parseresult.js:

// auto-generated by tools/rendering/precompilation/ — do not edit
export default {"template":[...],"iterates":{...}};

Runtime integration

import { template } from '@awacloud/fw/dom/rendering/template.js';
import precompiled from './nav.html.parseresult.json' assert { type: 'json' };

const tpl = template.factory(secPolicy.factory());
const pr  = tpl.fromParseResult(precompiled);
// pr has the same shape as parser.fromHTML(html) — pass to cmd.elms, etc.
tpl.elms('main', pr.template);

Browser support for JSON import assertions varies. The portable alternative is --esm, which emits a sibling .js:

import precompiled from './nav.html.parseresult.js';
const pr = tpl.fromParseResult(precompiled);

Notes / limitations

The tool fails fast with a clear diagnostic if parser.fromHTML() produces a value that is not JSON-serialisable (functions, class instances, DOM nodes, Maps, Sets). To date, all output is pure data.
--verify is recommended in CI: it confirms that the JSON written to disk is structurally identical to a fresh parse of the HTML source.
No runtime default value on map entries (always empty fallback) — for that need, use template.fromParseResult with runtime data.

Tests

bun test tools/rendering/precompilation/index.test.js

Covers parsing, CLI options, directory walk, --minify, --verify, --esm, and errors.