lighthouse-plugin-soft-navigation

Lighthouse Soft Navigation Plugin

This is a plugin for Lighthouse that measures metrics such as FCP and LCP in a soft navigation.

Definition

A soft navigation is a same-document navigation triggered by user interaction that mutates the DOM and updates the page URL (e.g. using the history API). You can read more about the definition of a soft navigation over in WICG/softnavigations.

Requirements

Warning These features are necessary for this plugin to work but they are experimental and therefore subject to change without warning. I will try to keep the plugin and requirements up to date as things change.

• Use the latest Chrome Canary.
• Launch Chrome with --enable-experimental-web-platform-features to enable soft navigation measurement.
• Add additionalTraceCategories: 'scheduler' to the Lighthouse config settings to collect the soft navigation trace events.

Installation

Install with npm or yarn. Make sure Lighthouse and Puppeteer are installed as well.

npm install lighthouse puppeteer lighthouse-plugin-soft-navigation

yarn add lighthouse puppeteer lighthouse-plugin-soft-navigation

Usage

Include this plugin in your Lighthouse config so Lighthouse timespan mode can audit interactions that trigger a soft navigation.

import fs from 'fs';
import puppeteer from 'puppeteer';
import {startFlow} from 'lighthouse';

const browser = await puppeteer.launch({
  headless: false,
  args: ['--enable-experimental-web-platform-features'],
  // Make sure you are using the latest Chrome Canary.
  executablePath: '/path/to/chrome'
});
const page = await browser.newPage();

const config = {
  extends: 'lighthouse:default',
  plugins: ['lighthouse-plugin-soft-navigation'],
  
  settings: {
    additionalTraceCategories: 'scheduler',
  },
}

const flow = await startFlow(page, {config});

// This will trigger a hard navigation.
// This step will be like any normal navigation in the report.
await flow.navigate('https://example.com');

// Clicking `a.link` will trigger a soft navigation.
// This step will include soft navigation metrics from the plugin in the report.
await flow.startTimespan();
await page.click('a.link');
await flow.endTimespan();

const report = await flow.generateReport();
fs.saveFileSync('report.html', report);