Quick start

This walkthrough takes you from an installed CLI to an opened Lighthouse report. It uses the public coffee cart demo as the target so you can follow along without an application of your own.

1. Create the configuration#

Run the init command and accept the default answer for every question:

npx user-flow init

The prompts write a .user-flowrc.json to the current folder:

{
  "collect": {
    "url": "https://coffee-cart.netlify.app/",
    "ufPath": "./user-flows"
  },
  "persist": {
    "outPath": "./measures",
    "format": ["html"]
  }
}

• collect.url is the page the browser opens first.
• collect.ufPath is the folder (or a single file) with your flows.
• persist.outPath is where reports are written.
• persist.format lists the report formats to produce.

2. Look at the generated flow#

When you confirm the "generate a flow" prompt, init creates user-flows/basic-navigation.uf.mts. It is the smallest useful flow: open the URL and measure the page load.

import { UserFlowInteractionsFn, UserFlowContext, UserFlowProvider } from '@push-based/user-flow';

// Your custom interactions with the page
const interactions: UserFlowInteractionsFn = async (ctx: UserFlowContext): Promise<any> => {
  const { page, flow, browser, collectOptions } = ctx;
  const { url } = collectOptions;

  // Navigate to URL
  await flow.navigate(url, {
    name: `Navigate to ${url}`,
  });
};

export default {
  flowOptions: { name: 'Order Coffee' },
  interactions,
} satisfies UserFlowProvider;

A flow file exports a UserFlowProvider with two parts:

• flowOptions names the flow. The name becomes the report title.
• interactions receives a context with the Puppeteer page and browser, the Lighthouse flow and the resolved collectOptions. Every flow.* call adds a step to the report.

3. Run it#

collect is the default command, so both of these do the same thing:

npx user-flow collect
# or simply
npx user-flow

The TypeScript file is compiled on the fly. Chrome starts, Lighthouse measures the navigation, the HTML report lands in ./measures and opens in your browser.

4. Override settings from the command line#

Any rc value can be overridden per run. This is how the same flow targets a local dev server:

npx user-flow --ufPath=./user-flows-new --outPath=./user-flows-reports --url=http://localhost:4200

Next steps#

• Add interactions and the other measurement modes in Basic user flows.
• Read the full option lists for init and collect.
• Put the flow into your pipeline with the GitHub workflow.