> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/GoogleChrome/lighthouse/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js quickstart

> Use Lighthouse programmatically as a Node module in your scripts and tooling.

The Lighthouse Node module gives you full programmatic control over audits. Use it to integrate Lighthouse into build scripts, test suites, or custom reporting pipelines.

<Note>Chrome must be installed on the machine running Lighthouse. The `chrome-launcher` package handles launching and connecting to it automatically.</Note>

<Steps>
  <Step title="Install dependencies">
    Install `lighthouse` and `chrome-launcher` as dev dependencies.

    <CodeGroup>
      ```bash npm theme={null}
      npm install --save-dev lighthouse chrome-launcher
      ```

      ```bash yarn theme={null}
      yarn add --dev lighthouse chrome-launcher
      ```
    </CodeGroup>
  </Step>

  <Step title="Write your first script">
    The following example launches a headless Chrome instance, runs a Lighthouse audit, saves an HTML report, and prints the performance score.

    ```js audit.js theme={null}
    import fs from 'fs';
    import lighthouse from 'lighthouse';
    import * as chromeLauncher from 'chrome-launcher';

    const chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});
    const options = {logLevel: 'info', output: 'html', onlyCategories: ['performance'], port: chrome.port};
    const runnerResult = await lighthouse('https://example.com', options);

    // `.report` is the HTML report as a string
    const reportHtml = runnerResult.report;
    fs.writeFileSync('lhreport.html', reportHtml);

    // `.lhr` is the Lighthouse Result as a JS object
    console.log('Report is done for', runnerResult.lhr.finalDisplayedUrl);
    console.log('Performance score was', runnerResult.lhr.categories.performance.score * 100);

    chrome.kill();
    ```

    Run it with:

    ```bash theme={null}
    node audit.js
    ```
  </Step>

  <Step title="Access the report and result object">
    The `lighthouse()` function returns a `RunnerResult` with two key properties:

    | Property  | Type     | Description                                                                      |
    | --------- | -------- | -------------------------------------------------------------------------------- |
    | `.report` | `string` | The report as an HTML, JSON, or CSV string, depending on the `output` option     |
    | `.lhr`    | `object` | The full Lighthouse Result (LHR) object with all audit data, scores, and metrics |

    Access category scores and individual audit results directly from `.lhr`:

    ```js theme={null}
    const lhr = runnerResult.lhr;

    // Category scores (0–1, multiply by 100 for display)
    console.log('Performance:', lhr.categories.performance.score * 100);
    console.log('Accessibility:', lhr.categories.accessibility.score * 100);
    console.log('SEO:', lhr.categories.seo.score * 100);
    console.log('Best Practices:', lhr.categories['best-practices'].score * 100);

    // Individual audit result
    const fcp = lhr.audits['first-contentful-paint'];
    console.log('FCP:', fcp.displayValue);
    ```
  </Step>

  <Step title="Run performance-only audits">
    Pass `onlyCategories` in the options object to limit which audit categories run. This reduces run time significantly when you only need specific data.

    ```js theme={null}
    const flags = {onlyCategories: ['performance']};
    const runnerResult = await lighthouse('https://example.com', flags);
    ```

    You can also pass multiple categories:

    ```js theme={null}
    const flags = {onlyCategories: ['performance', 'accessibility']};
    const runnerResult = await lighthouse('https://example.com', flags);
    ```
  </Step>
</Steps>

## Configuration

Pass a config object as the third argument to `lighthouse()` to customize audits beyond what flags allow:

```js theme={null}
const config = {
  extends: 'lighthouse:default',
  settings: {
    onlyAudits: [
      'speed-index',
      'interactive',
    ],
  },
};

const runnerResult = await lighthouse('https://example.com', {}, config);
```

Extend `lighthouse:default` to build on the standard configuration, or omit it to start from scratch.

See [Configuration overview](/configuration/overview) for all available options, and [Node API reference](/api/node-api) for the full API surface.