html-minifier-next 6.2.8 → 6.2.9

package/README.md

@@ -567,6 +567,8 @@ For CLI usage, using a config file is strongly recommended to avoid complex shel
 
 ## Working on HTML Minifier Next
 
+Note: This section assumes working with main dependencies installed (`npm i`).
+
 ### Local server
 
 ```shell
@@ -581,7 +583,7 @@ npm i;
 npm run backtest
 ```
 
-The backtest tool tracks minification performance across Git history. Results are saved in the backtest folder as CSV and JSON files.
+The backtest tool tracks minification performance across Git history. Results are saved in the backtest folder as a JSON file, results.json.
 
 Parameters:
 
@@ -589,6 +591,38 @@ Parameters:
 * `COUNT`: Tests last `COUNT` commits (e.g., `npm run backtest 100`)
 * `COUNT/STEP`: Tests last `COUNT` commits, sampling every `STEP`th commit (e.g., `npm run backtest 500/10` tests 50 commits)
 
+### Working tree benchmarks
+
+Where the backtest walks Git history, the benchmark times the code as it is _right now_—useful for A/B testing a branch against a saved baseline:
+
+```shell
+cd backtest;
+npm i;
+npm run benchmark
+```
+
+It reuses the backtest corpus (run `npm run backtest` once to download it) and reports per-file output size and median processing time.
+
+Parameters:
+
+* No argument: Runs and, if a baseline exists, shows size and time deltas
+* `--save`: Saves the run as the baseline (e.g., on `main` before switching to a branch)
+* `--core`: Disables the external minifiers (CSS, JS, SVG, URLs) to isolate HMN’s own processing time
+* `--iterations=N`: Sets the number of timed iterations (default 5; the median is reported)
+* `--config=PATH`: Uses an alternative options file (default `html-minifier.json`)
+
+To compare branches (A/B run), execute `npm run benchmark -- --save` on `main`, then `npm run benchmark` on the branch to see the deltas. Add `--core` on both ends when measuring changes to HMN’s own code rather than the bundled minifiers.
+
+#### Profiling
+
+To profile the current working tree, run the benchmark with Node’s built-in CPU profiler:
+
+```shell
+node --cpu-prof benchmark.js
+```
+
+This writes a `.cpuprofile` file to the working directory. Load it with `npx speedscope *.cpuprofile` for a flamegraph, or drag it into Chrome DevTools → Sources → JavaScript Profiler. Compare self-time per function against a clean baseline run on `main`. Pay attention to unexpectedly heavy callbacks in hot paths—V8 de-optimization from variable object shapes or unnecessary method calls can show up there.
+
 ## Acknowledgements
 
 With many thanks to the previous authors of and contributors to HTML Minifier, especially [Juriy “kangax” Zaytsev](https://github.com/kangax), and to everyone who helped make this new edition better, particularly [Daniel Ruf](https://github.com/DanielRuf), [Jonas Geiler](https://github.com/jonasgeiler), and [Chris Morgan](https://github.com/chris-morgan)!