### Install and Run Development Server

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/client/README.md

Commands to install dependencies, start the development server, and build the project for production.

```bash
pnpm install

pnpm dev

pnpm build
```

--------------------------------

### Quick Start: Scan Website Instantly

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/unlighthouse/README.md

Use `npx` to quickly scan a website without global installation. This command initiates a scan of the specified site using default settings.

```bash
# Scan your website instantly
npx unlighthouse --site https://example.com

# CI mode with performance budgets
npx unlighthouse-ci --site https://example.com --budget 80
```

--------------------------------

### start()

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/3.api-doc/index.md

Start the client and the queue worker. A server context must be provided before this function is called.

```APIDOC
## start()

### Description
Start the client and the queue worker. A server context must be provided before this function is called.

### Method
start

### Response
#### Success Response (200)
- **Promise<UnlighthouseContext>** - A promise that resolves with the Unlighthouse context.
```

--------------------------------

### Unlighthouse Configuration File Example

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/2.integrations/0.cli.md

Example of a `unlighthouse.config.ts` file to configure Unlighthouse settings.

```typescript
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'example.com',
  debug: true,
  scanner: {
    device: 'desktop',
  },
})
```

--------------------------------

### Install unlighthouse-ci

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/unlighthouse-ci/README.md

Install the package globally for command-line use or use it directly with npx.

```bash
npx unlighthouse-ci --site https://example.com
```

```bash
npm install -g unlighthouse-ci
```

--------------------------------

### Install and Run Unlighthouse CLI

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/cli/README.md

Install the CLI globally or use it directly with npx for website scanning.

```bash
npx unlighthouse --site https://example.com
```

```bash
npm install -g @unlighthouse/cli
```

--------------------------------

### Install Unlighthouse with pnpm

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/2.integrations/4.vite.md

Install the Unlighthouse Vite plugin as a development dependency using pnpm.

```bash
pnpm add -D @unlighthouse/vite
```

--------------------------------

### Install Unlighthouse CLI

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/generating-static-reports.md

Install the Unlighthouse CLI globally using npm, yarn, or pnpm.

```bash
npm install -g @unlighthouse/cli
```

```bash
yarn global add @unlighthouse/cli
```

```bash
pnpm install -g @unlighthouse/cli
```

--------------------------------

### Install Unlighthouse with npm

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/2.integrations/4.vite.md

Install the Unlighthouse Vite plugin as a development dependency using npm.

```bash
npm install -D @unlighthouse/vite
```

--------------------------------

### Install Unlighthouse with Yarn

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/2.integrations/4.vite.md

Install the Unlighthouse Vite plugin as a development dependency using Yarn.

```bash
yarn add -D @unlighthouse/vite
```

--------------------------------

### Run Unlighthouse CLI with npx

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/1.getting-started/0.installation.md

Use npx to run Unlighthouse directly without global installation. Replace 'example.com' with your target site.

```bash
npx unlighthouse --site example.com
```

--------------------------------

### Install Unlighthouse with npm

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/1.getting-started/0.installation.md

Install Unlighthouse globally using npm for frequent use. After installation, you can run the command directly.

```bash
npm install -g unlighthouse
unlighthouse --site example.com
```

--------------------------------

### Install Unlighthouse CLI and Puppeteer

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/2.integrations/1.ci.md

Install the Unlighthouse CLI and Puppeteer for CI environments. Puppeteer automatically downloads a compatible Chromium binary.

```bash
npm install -g @unlighthouse/cli puppeteer
```

--------------------------------

### Create and Start Unlighthouse Server

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/server/README.md

Use this snippet to initialize and launch the Unlighthouse server. Ensure necessary imports are included. The server instance and H3 app are returned for further configuration.

```typescript
import { createServer } from '@unlighthouse/server'

const { server, app } = await createServer()
// server is an instance of listhen, app is an instance of h3
await unlighthouse.setServerContext({ url: server.url, server: server.server, app })
await unlighthouse.start()
```

--------------------------------

### Install Unlighthouse Globally or as a Dev Dependency

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/unlighthouse/README.md

Install the package globally for command-line access or as a project dependency for local use.

```bash
# Global installation
npm install -g unlighthouse

# Project dependency
npm install unlighthouse --save-dev
```

--------------------------------

### Install and Run Unlighthouse CLI with Different Package Managers

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/1.getting-started/0.unlighthouse-cli.md

Install and run Unlighthouse using npm, pnpm, or yarn. This provides flexibility based on your preferred package manager.

```bash
npx unlighthouse --site https://mysite.com
```

```bash
pnpm dlx unlighthouse --site https://mysite.com
```

```bash
yarn dlx unlighthouse --site https://mysite.com
```

--------------------------------

### Install Unlighthouse Webpack Plugin

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/2.integrations/webpack.md

Install the Unlighthouse webpack plugin as a development dependency using yarn, npm, or pnpm.

```bash
yarn add -D @unlighthouse/webpack
```

```bash
npm install -D @unlighthouse/webpack
```

```bash
pnpm add -D @unlighthouse/webpack
```

--------------------------------

### Hook for task started

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/3.api-doc/index.md

Fired when a task begins its execution. Provides the path and response details of the task that has started.

```ts
hooks.hook('task-started', (path, response) => {
  // ...
})
```

--------------------------------

### Install Unlighthouse Globally

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/2.integrations/0.cli.md

Install the Unlighthouse package globally for frequent use. This makes the `unlighthouse` command available system-wide.

```bash
npm install -g unlighthouse
```

--------------------------------

### Configure Unlighthouse Scan

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/1.getting-started/0.installation.md

Define Unlighthouse configuration in `unlighthouse.config.ts`. This example sets the site, samples, throttle, and exclude paths.

```typescript
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  scanner: {
    samples: 3, // Run each page 3x and average (more accurate)
    throttle: true, // Simulate real network conditions
    exclude: ['/admin/*', '/api/*'], // Skip these paths
  },
})
```

--------------------------------

### Use Bundled Chromium

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/1.debugging.md

If Chrome fails to start, configure Unlighthouse to download and use its bundled Chromium version instead of relying on a system-installed Chrome.

```typescript
export default defineUnlighthouseConfig({
  chrome: {
    useSystem: false, // Download and use bundled Chromium
  },
})
```

--------------------------------

### Start Unlighthouse Scanning

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/1.getting-started/how-it-works.md

Starts the Unlighthouse scanning process. Can be initiated immediately in CLI mode or lazily upon first client access in integration mode.

```typescript
// CLI mode - starts immediately
unlighthouse.start()
```

```typescript
// Integration mode - waits for first client access
hooks.hookOnce('visited-client', () => {
  unlighthouse.start()
})
```

--------------------------------

### Customize Fallback Chrome Installer

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/chrome-dependency.md

Configure the fallback installer for Chrome binaries when system Chrome is unavailable or disabled. Options include disabling the fallback, specifying a version, and setting a cache directory for the downloaded binary.

```typescript
export default defineUnlighthouseConfig({
  chrome: {
    useDownloadFallback: true,
    downloadFallbackVersion: '1095492',
    downloadFallbackCacheDir: '/tmp/unlighthouse',
  },
})
```

--------------------------------

### UnlighthouseContext Methods

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/3.api-doc/glossary.md

Methods available on the UnlighthouseContext for managing server context, site URL, CI context, and starting the application.

```APIDOC
## setServerContext

### Description
To use Unlighthouse with a client, it needs a server / app to register the API and client middleware.

### Method
setServerContext

### Parameters
#### Request Body
- **arg** (ServerContextArg) - Required - The server context argument.

### Response
#### Success Response (UnlighthouseContext)
- Returns the UnlighthouseContext object after setting the server context.

### Request Example
```ts
// Assuming 'unlighthouse' is an instance of UnlighthouseContext
unlighthouse.setServerContext(serverContextArg)
```

### Response Example
```json
{
  "runtimeSettings": { ... },
  "hooks": { ... },
  "resolvedConfig": { ... },
  "api": { ... },
  "ws": { ... },
  "worker": { ... },
  "provider": { ... },
  "setServerContext": "function",
  "setSiteUrl": "function",
  "setCiContext": "function",
  "start": "function"
}
```
```

```APIDOC
## setSiteUrl

### Description
Sets the site URL that will be scanned if it's not known at initialisation.

### Method
setSiteUrl

### Parameters
#### Path Parameters
- **url** (string) - Required - The URL of the site to scan.

### Response
#### Success Response (void)
- This method does not return a value.

### Request Example
```ts
// Assuming 'unlighthouse' is an instance of UnlighthouseContext
unlighthouse.setSiteUrl('https://example.com')
```
```

```APIDOC
## setCiContext

### Description
Running Unlighthouse via CI does not require a server or the client so we have a special utility for it.

### Method
setCiContext

### Parameters
- None

### Response
#### Success Response (UnlighthouseContext)
- Returns the UnlighthouseContext object after setting the CI context.

### Request Example
```ts
// Assuming 'unlighthouse' is an instance of UnlighthouseContext
unlighthouse.setCiContext()
```

### Response Example
```json
{
  "runtimeSettings": { ... },
  "hooks": { ... },
  "resolvedConfig": { ... },
  "api": { ... },
  "ws": { ... },
  "worker": { ... },
  "provider": { ... },
  "setServerContext": "function",
  "setSiteUrl": "function",
  "setCiContext": "function",
  "start": "function"
}
```
```

```APIDOC
## start

### Description
Start the client and the queue worker. A server context must be provided before this function is called.

### Method
start

### Parameters
- None

### Response
#### Success Response (UnlighthouseContext)
- Returns the UnlighthouseContext object after starting the client and worker.

### Request Example
```ts
// Assuming 'unlighthouse' is an instance of UnlighthouseContext
unlighthouse.start()
```

### Response Example
```json
{
  "runtimeSettings": { ... },
  "hooks": { ... },
  "resolvedConfig": { ... },
  "api": { ... },
  "ws": { ... },
  "worker": { ... },
  "provider": { ... },
  "setServerContext": "function",
  "setSiteUrl": "function",
  "setCiContext": "function",
  "start": "function"
}
```
```

--------------------------------

### Install Unlighthouse Nuxt Module

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/2.integrations/3.nuxt.md

Add the Unlighthouse Nuxt module as a development dependency using your preferred package manager.

```bash
yarn add -D @unlighthouse/nuxt
```

```bash
npm install -D @unlighthouse/nuxt
```

```bash
pnpm add -D @unlighthouse/nuxt
```

--------------------------------

### visited-client Hook

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/3.api-doc/index.md

Called the first time a user visits the path of the `@unlighthouse/ui`. This is useful for starting the worker on-demand.

```APIDOC
### `visited-client`

#### Description
Called when a user visits the path of the `@unlighthouse/ui` for the first time. Useful for starting the worker on-demand.

#### Type
`() => HookResult`

#### Example
```ts
// only start when the user wants to see the client
hooks.hookOnce('visited-client', () => {
  unlighthouse.start()
})
```
```

--------------------------------

### Run Unlighthouse CLI with pnpm

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/1.getting-started/0.installation.md

Use pnpm to run Unlighthouse directly. This command is equivalent to the npm and yarn versions for installation and execution.

```bash
pnpm dlx unlighthouse --site https://mysite.com
```

--------------------------------

### Run Unlighthouse CLI with yarn

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/1.getting-started/0.installation.md

Use yarn to run Unlighthouse directly. This command is equivalent to the npm and pnpm versions for installation and execution.

```bash
yarn dlx unlighthouse --site https://mysite.com
```

--------------------------------

### task-started Hook

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/3.api-doc/index.md

Fired when a task has started processing.

```APIDOC
### `task-started`

#### Description
Fired when a task has started to work.

#### Type
`(path: string, response: UnlighthouseRouteReport) => HookResult`
```

--------------------------------

### Run unlighthouse-ci in CI Pipeline

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/2.integrations/1.ci.md

Install and run unlighthouse-ci with a site URL and a performance budget. The command exits with code 1 if the budget is failed, and 0 otherwise. This can be directly integrated into any bash-compatible CI pipeline.

```bash
npm install -g @unlighthouse/cli puppeteer
unlighthouse-ci --site https://staging.example.com --budget 80
```

--------------------------------

### useLogger()

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/3.api-doc/index.md

Get the global logger instance. This is useful for tight unlighthouse integrations which want to make use of the `debug` config.

```APIDOC
## useLogger()

### Description
Get the global logger instance. This is useful for tight unlighthouse integrations which want to make use of the `debug` config.

### Method
useLogger

### Request Example
```ts
import { useLogger } from '@unlighthouse/core'

// you need to instantiate the logger to get the instance
const logger = useLogger()
// force whichever route matches home.md to be re-scanned
logger.debug('Something weird has happened')
```

### Response
#### Success Response (200)
- **void** - This function returns the logger instance.
```

--------------------------------

### GitLab CI for Lighthouse Audits

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/2.integrations/1.ci.md

This GitLab CI configuration runs Unlighthouse audits using a Node.js image. It installs the CLI, performs the audit, and stores the generated reports as artifacts. Ensure the SITE_URL CI/CD variable is set.

```yaml
# .gitlab-ci.yml
lighthouse-audit:
  image: node:22
  script:
    - npm install -g @unlighthouse/cli puppeteer
    - unlighthouse-ci --site $SITE_URL --budget 75
  artifacts:
    paths:
      - .unlighthouse/
    expire_in: 1 week
```

--------------------------------

### CircleCI Configuration for Lighthouse Audits

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/2.integrations/1.ci.md

This CircleCI configuration uses a Node.js Docker image to run Unlighthouse audits. It checks out the code, installs the CLI, performs the audit with static report generation, and stores the artifacts. Ensure the SITE_URL context variable is configured.

```yaml
# .circleci/config.yml
version: 2.1
jobs:
  lighthouse:
    docker:
      - image: cimg/node:22.18.0-browsers
    steps:
      - checkout
      - run: npm install -g @unlighthouse/cli
      - run: unlighthouse-ci --site $SITE_URL --budget 75 --build-static
      - store_artifacts:
          path: .unlighthouse
```

--------------------------------

### createUnlighthouse()

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/3.api-doc/index.md

This is the entry point to using Unlighthouse, it will initialise Unlighthouse with the provided configuration and an optional provider. When no provider is given, a default provider is created which will try and resolve route definitions and URLs.

```APIDOC
## createUnlighthouse()

### Description
This is the entry point to using Unlighthouse, it will initialise Unlighthouse with the provided configuration and an optional provider. When no provider is given, a default provider is created which will try and resolve route definitions and URLs.

### Method
createUnlighthouse

### Parameters
#### Request Body
- **userConfig** (UserConfig) - Required - The user configuration object.
- **provider** (Provider) - Optional - The provider to use for Unlighthouse.

### Request Example
```ts
import { createUnlighthouse } from '@unlighthouse/core'

createUnlighthouse(
  // config
  { configFile: 'mysite.config.ts' },
  // provider
  {
    name: 'custom',
    // some custom implementation to find the route definitions
    routeDefinitions: () => generateRouteDefinitions(),
  }
)
```

### Response
#### Success Response (200)
- **UnlighthouseContext** - The Unlighthouse context object.
```

--------------------------------

### Set Up Server Context for UI

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/1.getting-started/how-it-works.md

Creates a local web server for the UI client and sets the server context within Unlighthouse for real-time updates and report serving.

```typescript
// Create server for the UI client
const { server, app } = await createServer()
await unlighthouse.setServerContext({
  url: server.url,
  server: server.server,
  app
})
```

--------------------------------

### Initialize Unlighthouse - Basic Usage

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/core/README.md

Use this to initialize Unlighthouse with basic configuration. Ensure the site URL is provided.

```typescript
import { createUnlighthouse } from '@unlighthouse/core'

const unlighthouse = await createUnlighthouse({
  site: 'https://example.com',
  debug: true,
  scanner: {
    device: 'desktop',
  }
})

await unlighthouse.start()
```

--------------------------------

### Advanced Un lighthouse CLI Options

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/cli/README.md

Utilize advanced options for multiple samples, throttling, custom URLs, exclusions, and configuration files.

```bash
unlighthouse --site https://example.com --samples 3 --throttle
```

```bash
unlighthouse --site https://example.com --urls /home,/about,/contact --exclude-urls /admin/*
```

```bash
unlighthouse --site https://example.com --config-file ./my-config.ts
```

--------------------------------

### Basic Configuration File

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/0.config.md

Create a `unlighthouse.config.ts` file in your project root to define site and scanner settings. The import is optional if you encounter resolution issues.

```typescript
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  scanner: {
    exclude: ['/admin/*', '/api/*'],
  },
})
```

--------------------------------

### createServer()

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/3.api-doc/index.md

Creates a h3 app which uses listhen as a web server. This is used to host the API and the client.

```APIDOC
## createServer()

### Description
Creates a h3 app which uses listhen as a web server. This is used to host the API and the client.

### Method
createServer

### Request Example
```ts
import { createServer } from '@unlighthouse/server'

// ...
const { server, app } = await createServer()
// server is an instance of listhen, app is an instance of h3
await unlighthouse.setServerContext({ url: server.url, server: server.server, app })
await unlighthouse.start()
```

### Response
#### Success Response (200)
- **Promise<void>** - A promise that resolves when the server is created.
```

--------------------------------

### Preview Static Report Locally

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/generating-static-reports.md

After generating the static report, you can preview it locally by serving the '.unlighthouse/client' directory using a simple HTTP server like sirv-cli.

```bash
npx sirv-cli .unlighthouse/client
```

--------------------------------

### Run CI with Configuration File

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/2.integrations/1.ci.md

Execute Unlighthouse CI scans using the defined configuration file. Assumes configuration is set up in 'unlighthouse.config.ts'.

```bash
unlighthouse-ci
```

--------------------------------

### Create Unlighthouse Server Instance

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/3.api-doc/index.md

The `createServer` function initializes an h3 app with listhen as the web server, used for hosting the API and client when Unlighthouse runs without an accessible web server, such as with the `cli` provider.

```typescript
import { createServer } from '@unlighthouse/server'

// ...
const { server, app } = await createServer()
// server is an instance of listhen, app is an instance of h3
await unlighthouse.setServerContext({ url: server.url, server: server.server, app })
await unlighthouse.start()
```

--------------------------------

### setServerContext()

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/3.api-doc/index.md

Initializes Unlighthouse to run with a client. This requires registering the API and client middleware with a server or application.

```APIDOC
## `setServerContext()`

### Description
Initializes Unlighthouse to run with a client. This requires registering the API and client middleware with a server or application.

### Method
`(arg: ServerContextArg) => Promise<UnlighthouseContext>`
```

--------------------------------

### Initialize Unlighthouse with Configuration and Provider

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/3.api-doc/index.md

Use `createUnlighthouse` to initialize Unlighthouse with user configuration and an optional custom provider. If no provider is specified, a default one is created to resolve route definitions and URLs.

```typescript
import { createUnlighthouse } from '@unlighthouse/core'

createUnlighthouse(
  // config
  { configFile: 'mysite.config.ts' },
  // provider
  {
    name: 'custom',
    // some custom implementation to find the route definitions
    routeDefinitions: () => generateRouteDefinitions(),
  }
)
```

--------------------------------

### Basic Un lighthouse CLI Scanning

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/cli/README.md

Perform basic website scans with options for debug mode and mobile simulation.

```bash
unlighthouse --site https://example.com
```

```bash
unlighthouse --site https://example.com --debug
```

```bash
unlighthouse --site https://example.com --mobile
```

--------------------------------

### Specify Custom Chrome Executable Path

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/chrome-dependency.md

Provide a custom path to your Chrome executable using `puppeteerOptions.executablePath`. This is useful if Chrome is installed in a non-standard location.

```typescript
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    executablePath: '/usr/bin/chrome',
  },
})
```

--------------------------------

### Basic CI Scan with Budget

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/2.integrations/1.ci.md

Scan a website and fail the build if any page scores below 75. Useful for enforcing performance standards.

```bash
# Scan site, fail if any page < 75
unlighthouse-ci --site example.com --budget 75
```

--------------------------------

### Programmatic Usage of Unlighthouse

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/unlighthouse/README.md

Integrate Unlighthouse into your applications by importing and creating an instance programmatically. Start scans and manage the process via the returned object.

```typescript
import { createUnlighthouse } from 'unlighthouse'

const unlighthouse = await createUnlighthouse({
  site: 'https://example.com',
  debug: true
})

await unlighthouse.start()
```

--------------------------------

### Run Default Unlighthouse Scan

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/2.integrations/0.cli.md

Execute a standard website scan using the Unlighthouse CLI. Ensure the site URL is provided.

```bash
unlighthouse --site example.com --debug
```

--------------------------------

### Get Global Logger Instance

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/3.api-doc/index.md

Use `useLogger` to retrieve the global logger instance, which is useful for Unlighthouse integrations that leverage the `debug` configuration setting.

```typescript
import { useLogger } from '@unlighthouse/core'

// you need to instantiate the logger to get the instance
const logger = useLogger()
// force whichever route matches home.md to be re-scanned
logger.debug('Something weird has happened')
```

--------------------------------

### CI Integration with Performance Budgets

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/unlighthouse/README.md

Utilize the `unlighthouse-ci` binary to enforce performance budgets within your continuous integration pipeline. This ensures that performance metrics meet predefined thresholds.

```bash
# Enforce performance budgets in CI
unlighthouse-ci --site https://example.com --budget 85
```

--------------------------------

### Disable System Chrome Usage

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/chrome-dependency.md

Set `chrome.useSystem` to `false` to prevent Unlighthouse from using your system's Chrome installation. This forces Unlighthouse to download and use its own compatible Chrome binary.

```typescript
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  chrome: {
    useSystem: false
  },
})
```

--------------------------------

### createUnlighthouse

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/core/README.md

Initializes the Unlighthouse engine with user-defined configuration and an optional custom provider.

```APIDOC
## createUnlighthouse(userConfig, provider?)

### Description
Initializes Unlighthouse with user configuration and an optional custom provider.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **userConfig** (object) - Required - User-defined configuration for Unlighthouse.
- **provider** (object) - Optional - A custom provider object with methods like `routeDefinitions`.
```

--------------------------------

### Generate Static Reports with unlighthouse-ci

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/2.integrations/1.ci.md

Use this command to generate a shareable HTML dashboard of lighthouse reports. Output is saved to the `.unlighthouse/` directory.

```bash
unlighthouse-ci --site example.com --build-static
```

--------------------------------

### Measure TTFB with Browser Console

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/glossary/ttfb.md

Run this script in your browser's developer console to measure TTFB and get a breakdown of its sub-parts. It categorizes the TTFB into 'good', 'needs-improvement', or 'poor' based on predefined thresholds.

```typescript
type Rating = 'good' | 'needs-improvement' | 'poor'

function rateValue(ms: number): Rating {
  return ms <= 800 ? 'good' : ms <= 1800 ? 'needs-improvement' : 'poor'
}

new PerformanceObserver((list) => {
  const nav = list.getEntriesByType('navigation')[0] as PerformanceNavigationTiming
  const ttfb = nav.responseStart

  const rating = rateValue(ttfb)
  console.log(`TTFB: ${ttfb.toFixed(0)}ms (${rating})`)

  // Sub-parts breakdown
  console.log('Breakdown:')
  console.log(`  DNS: ${(nav.domainLookupEnd - nav.domainLookupStart).toFixed(0)}ms`)
  console.log(`  TCP: ${(nav.connectEnd - nav.connectStart).toFixed(0)}ms`)
  console.log(`  SSL: ${(nav.connectEnd - (nav.secureConnectionStart || nav.connectStart)).toFixed(0)}ms`)
  console.log(`  Server: ${(nav.responseStart - nav.requestStart).toFixed(0)}ms`)
}).observe({ type: 'navigation', buffered: true })
```

--------------------------------

### GitHub Actions CI with Netlify Deployment

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/2.integrations/1.ci.md

This workflow automates Unlighthouse assertions and deploys a static report to Netlify. Ensure NETLIFY_AUTH_TOKEN and NETLIFY_SITE_ID secrets are configured in your GitHub repository.

```yaml
name: Assertions and static report

on:
  workflow_dispatch:

jobs:
  demo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Dependencies
        run: npm install -g @unlighthouse/cli puppeteer netlify-cli

      - name: Unlighthouse assertions and client
        run: unlighthouse-ci --site <your-site> --budget 75 --build-static

      - name: Deploy
        run: netlify deploy --dir=.unlighthouse --prod --message="New Release Deploy from GitHub Actions"
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
```

--------------------------------

### Disable System Chrome in Unlighthouse Config

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/common-errors.md

When facing browser connection errors, try disabling the system Chrome and using the fallback. This configuration change can resolve issues related to environment setup or firewall blocks.

```typescript
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  chrome: {
    useSystem: false,
  },
})
```

--------------------------------

### Run Unlighthouse Scan

Source: https://github.com/harlan-zw/unlighthouse/blob/main/README.md

Execute a website scan using Unlighthouse. Replace `<your-site>` with the target website URL. Supports both NPM and PNPM package managers.

```bash
npx unlighthouse --site <your-site>
# or PNPM
pnpm dlx unlighthouse --site <your-site>
```

--------------------------------

### Basic CI Scan with unlighthouse-ci

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/unlighthouse-ci/README.md

Run a basic CI scan with default performance budget or specify a custom budget.

```bash
unlighthouse-ci --site https://example.com
```

```bash
unlighthouse-ci --site https://example.com --budget 85
```

--------------------------------

### Hook for first client visit

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/3.api-doc/index.md

This hook fires the first time a user accesses the `@unlighthouse/ui` path. It's useful for initiating the worker on-demand when the UI is first viewed.

```ts
// only start when the user wants to see the client
hooks.hookOnce('visited-client', () => {
  unlighthouse.start()
})
```

--------------------------------

### Configure Basic Auth

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/authentication.md

Use this for sites with HTTP Basic Authentication. Configure via config file or CLI.

```typescript
export default defineUnlighthouseConfig({
  auth: {
    username: process.env.AUTH_USER,
    password: process.env.AUTH_PASS,
  },
})
```

```bash
unlighthouse --site staging.example.com --auth admin:secretpass
```

--------------------------------

### Run Unlighthouse from the Command Line

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/unlighthouse/README.md

Execute scans directly from your terminal using the `unlighthouse` command. Options include specifying the site, enabling debugging, setting the device type, or using a custom configuration file.

```bash
# Basic scan
unlighthouse --site https://example.com

# With debugging and custom device
unlighthouse --site https://example.com --debug --desktop

# Custom configuration
unlighthouse --config-file unlighthouse.config.ts
```

--------------------------------

### Migrate to Unlighthouse CLI

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/integration-deprecations.md

Use the CLI integration as a replacement for deprecated build tool integrations. This command initiates a scan for the specified site.

```bash
npx unlighthouse --site localhost:3000
```

--------------------------------

### useUnlighthouse()

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/3.api-doc/index.md

Unlighthouse makes use of a composition API to retain the core state. This allows you to access unlighthouse _anywhere_, which is great to avoid transferring state between your logic.

```APIDOC
## useUnlighthouse()

### Description
Unlighthouse makes use of a composition API to retain the core state. This allows you to access unlighthouse _anywhere_, which is great to avoid transferring state between your logic.

### Method
useUnlighthouse

### Request Example
```ts
import { useUnlighthouse } from '@unlighthouse/core'

// access the lighthouse context, pick out the worker
const { worker } = useUnlighthouse()
// force whichever route matches home.md to be re-scanned
worker.invalidateFile('/home.md')
```

### Response
#### Success Response (200)
- **UnlighthouseContext** - The Unlighthouse context object.
```

--------------------------------

### Run Multiple Samples Per URL

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/recipes/improving-accuracy.md

Configure Lighthouse to run multiple scans for each URL and average the results. Use `samples: 3` for development and `samples: 5` for CI/production audits.

```typescript
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  scanner: {
    samples: 3, // Run 3 scans per URL and average results
  },
})
```

--------------------------------

### Upload to Lighthouse CI with Basic Auth

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/generating-static-reports.md

To upload reports to a Lighthouse CI server with basic authentication, use the `--lhci-auth` flag along with your username and password.

```bash
unlighthouse-ci --site <your-site> --reporter lighthouseServer --lhci-host <lhci host> --lhci-build-token <lhci buildToken> --lhci-auth <username>:<password>
```

--------------------------------

### GitHub Actions for Netlify Deployment

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/generating-static-reports.md

This GitHub Actions workflow generates Unlighthouse assertions and a static client build, then deploys the report to Netlify. It requires Netlify authentication tokens and site ID to be set as secrets.

```yaml
name: Assertions and static report

on:
  workflow_dispatch:

jobs:
  demo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Dependencies
        run: npm add -g @unlighthouse/cli puppeteer

      - name: Unlighthouse assertions and client
        run: unlighthouse-ci --site <your-site> --build-static

      - name: Deploy report to Netlify
        uses: nwtgck/actions-netlify@v3.0
        with:
          publish-dir: ./.unlighthouse
          production-branch: main
          production-deploy: true
          github-token: ${{ secrets.GITHUB_TOKEN }}
          deploy-message: New Release Deploy from GitHub Actions
          enable-pull-request-comment: false
          enable-commit-comment: true
          overwrites-pull-request-comment: true
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_DEMO_SITE_ID }}
        timeout-minutes: 1
```

--------------------------------

### Recommended Production Configuration

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/recipes/improving-accuracy.md

Combine multiple samples, network throttling, and a single worker for the most accurate results. Be aware that higher accuracy significantly increases scan time.

```typescript
export default defineUnlighthouseConfig({
  scanner: {
    samples: 5,
    throttle: true,
  },
  puppeteerClusterOptions: {
    maxConcurrency: 1,
  },
})
```

--------------------------------

### generateClient()

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/3.api-doc/index.md

This copies over the client from `@unlighthouse/ui` to be used to render our scans details. It's publicly exposed to provide a tight integrations for custom client builds, such as the CI build.

```APIDOC
## generateClient()

### Description
This copies over the client from `@unlighthouse/ui` to be used to render our scans details. It's publicly exposed to provide a tight integrations for custom client builds, such as the CI build.

### Method
generateClient

### Parameters
#### Request Body
- **options** (GenerateClientOptions) - Required - Options for generating the client.

### Request Example
```ts
import { generateClient } from '@unlighthouse/core'

// ...
logger.info('Generating static client.')
await generateClient({ static: true })
logger.success(`Static client generated at 
	`${unlighthouse.runtimeSettings.generatedClientPath}
	`, ready for hosting.
`)
```

### Response
#### Success Response (200)
- **void** - This function does not return a value.
```

--------------------------------

### Specify Configuration File via CLI

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/0.config.md

Use the `--config-file` flag to specify a custom configuration file path.

```bash
unlighthouse --config-file ./configs/production.config.ts
```

--------------------------------

### Upload to Lighthouse CI Server

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/generating-static-reports.md

Use the `--reporter lighthouseServer` flag to upload reports directly to a Lighthouse CI server. You must provide the `--lhci-host` and `--lhci-build-token` flags.

```bash
unlighthouse-ci --site <your-site> --reporter lighthouseServer --lhci-host <lhci host> --lhci-build-token <lhci buildToken>
```

--------------------------------

### Configure Authentication

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/0.config.md

Set up basic authentication using `auth.username` and `auth.password`, or cookie-based authentication with the `cookies` array. Environment variables are recommended for sensitive credentials.

```typescript
export default defineUnlighthouseConfig({
  // Basic auth
  auth: {
    username: process.env.AUTH_USER,
    password: process.env.AUTH_PASS,
  },
  // Cookie auth
  cookies: [
    { name: 'session', value: process.env.SESSION_TOKEN, domain: '.example.com' },
  ],
})
```

--------------------------------

### Un lighthouse Configuration File

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/cli/README.md

Define custom Unlighthouse configurations using a TypeScript file.

```typescript
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  debug: true,
  scanner: {
    device: 'desktop',
    throttle: false,
  },
  lighthouseOptions: {
    onlyCategories: ['performance', 'accessibility'],
  }
})
```

--------------------------------

### Run Unlighthouse in Desktop Mode via CLI

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/device.md

Use the --desktop flag in the CLI to override default mobile emulation and scan using a desktop viewport. This flag takes precedence over config file settings.

```bash
npx unlighthouse --site https://example.com --desktop
```

--------------------------------

### JSON Report Sample

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/generating-static-reports.md

This is a sample of the JSON report format, showing URL and core performance metrics.

```json
[
  {
    "path": "/",
    "score": 0.97,
    "performance": 0.87,
    "accessibility": 1,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/blog",
    "score": 0.98,
    "performance": 0.91,
    "accessibility": 1,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/blog/2023-february",
    "score": 0.91,
    "performance": 0.65,
    "accessibility": 1,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/blog/modern-package-development",
    "score": 0.9,
    "performance": 0.61,
    "accessibility": 0.97,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/blog/scale-your-vue-components",
    "score": 0.87,
    "performance": 0.51,
    "accessibility": 0.97,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/blog/vue-automatic-component-imports",
    "score": 0.88,
    "performance": 0.53,
    "accessibility": 0.97,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/blog/vue-use-head-v1",
    "score": 0.97,
    "performance": 0.9,
    "accessibility": 0.97,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/projects",
    "score": 0.94,
    "performance": 0.77,
    "accessibility": 1,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/sponsors",
    "score": 0.97,
    "performance": 0.88,
    "accessibility": 1,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/talks",
    "score": 0.94,
    "performance": 0.74,
    "accessibility": 1,
    "best-practices": 1,
    "seo": 1
  }
]
```

--------------------------------

### Define Unlighthouse Configuration

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/unlighthouse/README.md

Create a configuration file (e.g., `unlighthouse.config.ts`) to customize scan settings. This includes specifying the target site, scanner device, throttling, and Lighthouse options like categories to include.

```typescript
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  scanner: {
    device: 'desktop',
    throttle: false,
  },
  lighthouseOptions: {
    onlyCategories: ['performance', 'accessibility'],
  }
})
```

--------------------------------

### setCiContext()

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/3.api-doc/index.md

Initializes Unlighthouse for a CI environment. This utility is designed for running Unlighthouse without needing a server or client.

```APIDOC
## `setCiContext()`

### Description
Initializes Unlighthouse for a CI environment. This utility is designed for running Unlighthouse without needing a server or client.

### Method
`() => Promise<UnlighthouseContext>`
```

--------------------------------

### Enable Debug Logging

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/1.debugging.md

Run Unlighthouse with the --debug flag to see detailed logs about URL discovery, page scanning, errors, and Chrome connection status. This is the first step for diagnosing most issues.

```bash
unlighthouse --site example.com --debug
```

--------------------------------

### Desktop Scan with Custom Output

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/unlighthouse-ci/README.md

Perform a desktop scan and specify a custom path for the output reports.

```bash
unlighthouse-ci --site https://example.com --desktop --output-path ./lighthouse-reports
```

--------------------------------

### Advanced CI Configuration

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/unlighthouse-ci/README.md

Configure advanced CI settings by creating a `unlighthouse.config.ts` file. This allows for custom site URLs, budgets, static build options, and Lighthouse specific configurations.

```typescript
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  ci: {
    budget: 80,
    buildStatic: true,
  },
  lighthouseOptions: {
    onlyCategories: ['performance', 'accessibility', 'seo'],
  }
})
```

--------------------------------

### Un lighthouse CI Integration

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/cli/README.md

Integrate Unlighthouse into CI workflows with exit codes for failed audits based on budgets.

```bash
unlighthouse-ci --site https://example.com --budget 75
```

--------------------------------

### Initialize Unlighthouse - Custom Provider

Source: https://github.com/harlan-zw/unlighthouse/blob/main/packages/core/README.md

Initialize Unlighthouse with a custom provider for advanced configuration. This allows for custom route definitions.

```typescript
import { createUnlighthouse } from '@unlighthouse/core'

const unlighthouse = await createUnlighthouse(
  { /* user config */ },
  {
    name: 'custom',
    routeDefinitions: () => generateRouteDefinitions(),
  }
)
```

--------------------------------

### Upload Reports to LHCI Server

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/2.integrations/1.ci.md

Upload scan results to an existing Lighthouse CI server. Requires LHCI host and build token.

```bash
unlighthouse-ci --site example.com \
  --reporter lighthouseServer \
  --lhci-host https://lhci.yourcompany.com \
  --lhci-build-token $LHCI_TOKEN
```

--------------------------------

### Generate and Deploy to Cloudflare Pages

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/generating-static-reports.md

This command generates the static report and then uses the wrangler CLI to publish the '.unlighthouse' directory to Cloudflare Pages. Ensure wrangler is initialized and configured.

```bash
unlighthouse-ci --site www.example.com --build-static && wrangler pages publish .unlighthouse
```

--------------------------------

### CI Scan with Budget and Static Report

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/2.integrations/1.ci.md

Combines budget checking and static report generation for comprehensive CI performance checks.

```bash
# Both: budget check + report
unlighthouse-ci --site example.com --budget 75 --build-static
```

--------------------------------

### Provide Manual Sitemap Paths

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/url-discovery.md

Specify an array of sitemap file paths to be scanned. Unlighthouse will use these instead of relying on robots.txt or the default '/sitemap.xml'.

```typescript
export default defineUnlighthouseConfig({
  scanner: {
    sitemap: [
      '/sitemap.xml',
      '/sitemap2.xml',
    ],
  },
})
```

--------------------------------

### Generate Static HTML Report

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/generating-static-reports.md

Generate a static, self-hosted HTML report for your site. The output is saved to the default '.unlighthouse' directory, with the client files located in '.unlighthouse/client'. This directory can then be uploaded to any static host.

```bash
unlighthouse-ci --site <your-site> --build-static
```

--------------------------------

### Audit Website with Unlighthouse CLI

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/glossary/index.md

Use the Unlighthouse CLI to scan your entire website and identify pages needing performance improvements. This command initiates a comprehensive audit.

```bash
npx unlighthouse --site https://example.com
```

--------------------------------

### Configure Pages Directory and File Extensions

Source: https://github.com/harlan-zw/unlighthouse/blob/main/docs/1.guide/guides/route-definitions.md

Modify the 'pagesDir' and 'fileExtensions' options to customize how Unlighthouse discovers route files. This is useful when your project structure differs from the default.

```typescript
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  root: './app',
  discovery: {
    pagesDir: 'routes',
    fileExtensions: ['jsx', 'md'],
  },
})
```