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.

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'],
}

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);