soft-navigation
@push-based/lighthouse-soft-navigationv0.0.1

Soft navigations, measured as navigations.

Stock Lighthouse fails on a route change that never loads a document. One config turns it into a navigation step with FCP, LCP and a Performance score.

Get started GitHub
Terminal
# install and run a flow with a soft navigation
$ npm i @push-based/lighthouse-soft-navigation
$ node flow.mjs
✔ shop.example/ · page load · performance 88
✔ shop.example/products · soft navigation · performance 97
→ flow.report.html
$

How it works

From a route change to a score in four steps

  1. Installnpm i @push-based/lighthouse-soft-navigationNext to Lighthouse 13.6, with Chrome 149 or newer.
  2. Pass the configsoftNavigationConfig()Give it to startFlow. Every other step runs exactly as before.
  3. Click a routeflow.navigate(() => page.click(…))A navigation step that stays in the document is a soft navigation.
  4. Read the stepFCP · LCP · PerformanceStock metrics and scoring, measured from the click.

What you get

Route changes, scored like page loads

Lighthouse user flow report

Browse the shop

Sample
  1. Open the shopNavigation report · page load
    • Performance
    • Accessibility
    • Best practices
    • SEO
  2. Open the product listNavigation report · soft navigation
    • Performance
    • Accessibility
    • Best practices
    • SEO
  3. Add to cartTimespan report
    • Performance
    • Best practices
The soft navigation is a navigation step with a Performance score, next to the page load and the timespan of the same flow. Reading the results →

Why this package

Measure what users wait for after a click

A score for every route change

A click that only changes the route is a navigation step with FCP, LCP, Speed Index, TBT and a Performance score, instead of a NO_FCP error.

One config, no flag

Pass softNavigationConfig() to startFlow. The package recognises a soft navigation from what the browser does, so your steps stay as they are.

Stock Lighthouse underneath

The metrics come from Lighthouse's own audits and scoring curves. The package only supplies the events they need, with the click as time origin.

Every category scored

Audits of the document response do not apply to a route change and report notApplicable, so no audit errors and no missing scores.

Mixes with every step

Page loads, timespans and snapshots run exactly as before. Measure the route change, then the interactions on the new page, in one flow.

Built to land in Lighthouse

Each override maps to a change in Lighthouse itself, and the result has the shape upstream support will produce. Swapping later is mechanical.

Documentation

Find your way around

Getting started

Guides

Reference

Upstreaming

Resources

Ready to measure your route changes?

One config turns the soft navigations of your app into navigation steps with a Performance score.

Read the quick start

All pages

  • Getting started Introduction Introduction What a soft navigation is, why stock Lighthouse cannot measure one and what the package changes.
  • Getting started Installation Installation Install the package next to Lighthouse, and the Lighthouse and Chrome versions it needs.
  • Getting started Quick start Quick start Run a user flow with a page load and a soft navigation, and open the flow report.
  • Guides Soft navigation steps Soft navigation steps Write soft navigation steps with a callback or with startNavigation, and how the package recognises them.
  • Guides Reading the results Reading the results The shape of a soft navigation step, its metrics, the audits that do not apply and its run warnings.
  • Guides Throttling Throttling Why a soft navigation step needs DevTools or provided throttling instead of simulated throttling.
  • Guides Limits and troubleshooting Limits and troubleshooting What a soft navigation step cannot measure, and what to do when a step fails or has a warning.
  • Reference API API softNavigationConfig, the gatherers and audits it is built from, and the exported run warnings.
  • Reference How it works How it works How the gatherers, the trace and the wrapped audits turn a soft navigation into a navigation step.
  • Upstreaming Upstreaming to Lighthouse Upstreaming to Lighthouse The target behaviour in Lighthouse, why the package cannot use the same flag and how it stays swappable.
  • Upstreaming Override map Override map Each override of the package next to the Lighthouse change it stands in for, with the files involved.
  • Upstreaming Landing plan Landing plan The proposed sequence of Lighthouse pull requests and the open questions for the Lighthouse team.
  • Resources Links Links The Lighthouse issues and pull requests, Chrome soft navigation docs and related tools.