lightstack

Run Lighthouse on every page in your TanStack Start / TanStack Router project.

lightstack reads the generated TanStack route tree, finds page routes, runs Lighthouse on each page, and writes one reduced Lighthouse-shaped JSON report per successful page. By default it looks for src/routeTree.gen.ts.

Requirements:

• Node.js 20 or newer.
• A running local app server, for example a TanStack Start dev or preview server.
• Chrome or Chromium available to Lighthouse.

pnpm exec lightstack --base-url=http://127.0.0.1:3000
pnpm exec lightstack --base-url=http://127.0.0.1:3000 -- --preset=desktop
npx lightstack --base-url=http://127.0.0.1:3000 --only=/,/checkout

By default the route planner skips routes that are usually not pages:

• /api and /api/* routes. Pass --include-api to run Lighthouse on them.
• Asset-like route files such as .xml, .json, or .tsv. Pass --include-assets to run Lighthouse on them.
• Dynamic routes until you provide concrete values with --route-param.

Each run is written under .lightstack/lighthouse/<run-id>/:

.lightstack/lighthouse/2026-05-25T02-36-48Z/home.json
.lightstack/lighthouse/2026-05-25T02-36-48Z/checkout.json
.lightstack/lighthouse/2026-05-25T02-36-48Z/manifest.json

At the end of a real Lighthouse run, the CLI prints the manifest file URL:

Result manifest: file:///your/project/.lightstack/lighthouse/2026-05-25T02-36-48Z/manifest.json

manifest.json is only a table of contents: route path, source file when resolved, status, report file, optional raw report file, and error file for failed routes. The page report is the main artifact.

The cleaned page report keeps the Lighthouse report shape but removes bulk that is not useful for code agents: not-applicable/manual audits, screenshots and base64 image data, passing audits, internal timing/i18n/config/category group data, zero-weight audit refs, and low-value text/geometry fields noted in reports/notes.md.

Full Lighthouse JSON is not retained by default. Pass --raw to keep untouched reports under .lightstack/lighthouse/<run-id>/raw/ while still writing the cleaned page report at the run root.

You can also wire the local repo script:

{
  "scripts": {
    "lighthouse": "lightstack"
  }
}

Pass Lighthouse-specific arguments after --:

pnpm exec lightstack --base-url=http://127.0.0.1:3000 -- --preset=desktop --throttling-method=provided

Dynamic TanStack routes are included when you provide values:

pnpm exec lightstack --base-url=http://127.0.0.1:3000 --route-param orderID=ord_123

Repeat a route param to run Lighthouse on multiple dynamic path values:

pnpm exec lightstack \
  --base-url=http://127.0.0.1:3000 \
  --route-param Size=tracksuits \
  --route-param Size=sweatsuits \
  --route-param Size=t-shirts

Search-param URL variants are explicit and route-scoped:

pnpm exec lightstack \
  --base-url=http://127.0.0.1:3000 \
  --route-param Size=tracksuits \
  --search-param '/sizing/tracksuits?part=top' \
  --search-param '/sizing/tracksuits?part=bottom' \
  --search-param '/orders?order_id=ord_123'

Useful project options:

• --route-tree <file>: use a generated tree outside src/routeTree.gen.ts.
• --output-dir <dir>: choose the Lighthouse report root.
• --raw: retain full Lighthouse JSON under the run's raw/ directory.
• --only <list>: run Lighthouse on selected route names or paths.
• --route-param <name=value>: add one dynamic path value; repeat for more.
• --include-api: include /api routes.
• --include-assets: include asset-like routes.
• --search-param <route?key=value>: add a query-string route variant.
• --dry-run: print the route plan without launching Lighthouse.
• --list: print only runnable route paths without launching Lighthouse.
• --concurrency <n>: run multiple Lighthouse jobs at once.
• --fast: local triage shortcut for --concurrency=2.
• --fail-fast: stop after the first Lighthouse failure; this forces serial execution.
• --headless: add Lighthouse Chrome headless flags.
• --no-headless: do not add default Chrome headless flags.

Concurrency defaults to 1. Parallel Lighthouse runs are useful for fast local triage, but final numbers are more stable when left serial. You can also set LIGHT_STACK_CONCURRENCY.

Author

Built by Warya Wayne, @waryawayne.

• GitHub: @WaryaWayne
• X: @waryawayne