@kbn/perf-page-load

Lighthouse performance benchmarking CLI for Kibana. Measures page-load performance (FCP, LCP, TBT, TTI, CLS, Speed Index) and Kibana-specific custom metrics (first_app_nav, bootstrap_started) against dev or production dist builds.

Prerequisites

yarn kbn bootstrap

Commands

run — Single benchmark

Run a Lighthouse audit against the current checkout.

node scripts/perf_page_load.js run [--dist] [--throttle devtools] [--output path]

Examples:

# Dev mode, no throttling
node scripts/perf_page_load.js run

# Dist build with realistic throttling
node scripts/perf_page_load.js run --dist --throttle devtools

# Save results to a file
node scripts/perf_page_load.js run --output results/baseline.json

compare — Compare two saved result files

Compare two previously saved JSON result files offline, without re-running benchmarks.

node scripts/perf_page_load.js compare <file1> <file2> [--threshold 5]

For each metric, the delta column is a percent change vs the baseline. When the baseline value is 0 and the comparison is non-zero, the change is expressed vs a small baseline floor so the percentage stays defined and comparable to --threshold: 1 ms for millisecond metrics, 0.01 for CLS. When both values are 0, the delta is 0%.

Example:

node scripts/perf_page_load.js run --output before.json
# ... make changes ...
node scripts/perf_page_load.js run --output after.json
node scripts/perf_page_load.js compare before.json after.json --threshold 3

compare-refs — Compare two git refs

Check out each ref into a temporary worktree, bootstrap, optionally build dist bundles, run Lighthouse, and compare results.

node scripts/perf_page_load.js compare-refs <ref1> <ref2> [--dist] [--throttle devtools] [--threshold 5]

Examples:

# Compare two commits
node scripts/perf_page_load.js compare-refs abc1234 def5678 --dist --throttle devtools

# Compare HEAD against a specific commit
node scripts/perf_page_load.js compare-refs HEAD abc1234 --dist

# Compare HEAD against main
node scripts/perf_page_load.js compare-refs HEAD main --dist --throttle devtools

Note: Each ref goes through a full bootstrap + build + Lighthouse cycle in an isolated worktree. Expect 15-30 minutes per ref depending on whether --dist is used.

compare-optimizers — Legacy vs Rspack (rspack-transition)

Run back-to-back benchmarks on the current working tree — first with the legacy Webpack optimizer, then with Rspack — and output a side-by-side comparison.

node scripts/perf_page_load.js compare-optimizers [--dist] [--throttle devtools] [--threshold 5]

Example:

node scripts/perf_page_load.js compare-optimizers --dist --throttle devtools

Note: This command is tagged [rspack-transition] and will be removed when the legacy optimizer is fully deprecated. Legacy runs first to avoid stale shared-deps artifacts.

Use cases

Compare performance across two commits

node scripts/perf_page_load.js compare-refs abc1234 def5678 --dist --throttle devtools

Compare current work against a baseline commit

node scripts/perf_page_load.js compare-refs HEAD abc1234 --dist

Compare a PR against its base branch

Self-contained check that benchmarks the PR tip against the merge base with main (or any target branch). Uses git merge-base which is always available — no external tools required.

# Find the common ancestor between HEAD and the target branch
MERGE_BASE=$(git merge-base HEAD origin/main)
node scripts/perf_page_load.js compare-refs HEAD "$MERGE_BASE" --dist --throttle devtools --threshold 5

In CI, most systems provide the target branch as an environment variable (e.g., Buildkite: BUILDKITE_PULL_REQUEST_BASE_BRANCH, GitHub Actions: GITHUB_BASE_REF). Use it directly:

MERGE_BASE=$(git merge-base HEAD "origin/$TARGET_BRANCH")
node scripts/perf_page_load.js compare-refs HEAD "$MERGE_BASE" --dist --throttle devtools --threshold 5

Incremental development workflow

Save results before and after changes, then compare offline:

node scripts/perf_page_load.js run --output before.json
# ... make changes ...
node scripts/perf_page_load.js run --output after.json
node scripts/perf_page_load.js compare before.json after.json --threshold 3

Quick reference

Add --dist to any command to benchmark production bundles, and --throttle devtools for realistic network/CPU conditions.

Metrics collected

How custom Kibana metrics are extracted

Kibana emits performance.mark('kbnLoad', { detail: 'phase_name' }) at key lifecycle points. The Lighthouse user-timings audit strips the detail property when building its table, so we bypass the audit and read directly from artifacts.Trace.traceEvents where Chrome serializes the full mark data including args.data.detail.

Environment variables

Pages benchmarked

The default spec audits two pages:

1. Home — /app/home
2. eCommerce Dashboard — /app/dashboards#/view/722b74f0-b882-11e8-a6d9-e546fe2bba5f