@vocento/wpo-check/README.md

An internal CLI tool to measure and validate Web Performance KPIs during development and CI/CD workflows.

# WPO Check

An internal CLI tool to measure and validate Web Performance KPIs during development and CI/CD workflows.

## Table of Contents

- [Installation and Usage](#installation-and-usage)
  - [Options](#options)
- [Configuration](#configuration)
  - [Properties](#properties)
- [Thresholds](#thresholds)
- [Output](#output)
- [License](#license)

## Installation and Usage

Prerequisites: [Node.js](https://nodejs.org/) (`^20.19.2`).

**Note**: It is recommended to use [*Node Version Manager*](https://github.com/creationix/nvm) (`nvm`).

You can run WPO Check on any url like this:

```shell
npx wpo-check http://localhost:3000
```

### Options

```
{
  --mode: development | production,
  --report: Report export path (JSON),
  --thresholds: Path to the custom file with thresholds,
  --config: Path to the configuration file,
}
```

## Configuration

You can configure rules in your `.wpo-check.config.json` files as in this example:

```js
{
  "routes": [
    "http://localhost:3000",
    "http://localhost:3000/login",
    "http://localhost:3000/dashboard"
  ],
  "settings": {
    "throttling": 0,
    "cpuSlowdown": 0,
    "viewport": "1366x768",
    "device": "desktop",
  }
}
```

### Properties

Below are the available configuration properties for the `.wpo-check.config.json` file. These allow you to customize which URLs are audited and how the audits are performed, including device emulation, throttling, and viewport settings.

| Name | Type | Default | Description |
| ----------- | :------: | :-------------------------: | ------------------------------------------------------------------------------------------------------------------ |
| routes      | string[] | `[]`                        | Array of URLs to run Lighthouse audits on.                                                                         |
| settings    | Object   | `{}`                        | Configuration object containing audit options.                                                                     |
| throttling  | number   | `0`                         | Performance throttling level (`0` = none, `1` = low, `2` = high).                                                  |
| cpuSlowdown | number   | `0`                         | CPU slowdown multiplier (`0` = none, `1` = 2x, `2` = 4x).                                                          |
| viewport    | string   | `"412x823"` or `"1350x940"` | Viewport size in the format `${width}x${height}`. Defaults to `"412x823"` for mobile and `"1350x940"` for desktop. |
| device      | string   | `"mobile"`                  | Emulated device type, either `"mobile"` or `"desktop"`.                                                            |

## Thresholds

You can customize thresholds by creating a `.wpo-check.thresholds.json` file. Example:

```json
{
  "lcp": { "value": 2.5, "critical": true, "unit": "s" },
  "inp": { "value": 200, "critical": true, "unit": "ms" },
  "cls": { "value": 0.1, "critical": true, "unit": "" },
  "fid": { "value": 100, "critical": false, "unit": "ms" },
  "fcp": { "value": 1.8, "critical": false, "unit": "s" },
  "ttfb": { "value": 200, "critical": false, "unit": "ms" },
  "tbt": { "value": 200, "critical": false, "unit": "ms" },
  "size": { "value": 1.5, "critical": false, "unit": "MB" },
  "networkRequests": { "value": 100, "critical": false, "unit": "" },
  "domSize": { "value": 1500, "critical": false, "unit": "" },
  "domDepth": { "value": 32, "critical": false, "unit": "" }
}
```

Below is a description of each available metric and its meaning:

| Metric            | Name                          | Unit     | Description                                                                                   |
|-------------------|-------------------------------|:--------:|-----------------------------------------------------------------------------------------------|
| lcp               | Largest Contentful Paint      | `s`      | Time until the largest content element is visible.                                            |
| inp               | Interaction to Next Paint     | `ms`     | Measures input responsiveness.                                                                |
| cls               | Cumulative Layout Shift       |          | Quantifies unexpected layout shifts during page load.                                         |
| fid               | First Input Delay             | `ms`     | Time from user interaction to browser response.                                               |
| fcp               | First Contentful Paint        | `s`      | Time until the first content is painted.                                                      |
| ttfb              | Time To First Byte            | `ms`     | Time until the first byte is received from the server.                                        |
| tbt               | Total Blocking Time           | `ms`     | Total time main thread was blocked preventing input responsiveness.                           |
| size              | Page Weight                   | `MB`     | Total page weight in megabytes.                                                               |
| networkRequests   | Network Requests              |          | Number of network requests made during page load.                                             |
| domSize           | DOM Nodes                     |          | Total number of DOM nodes.                                                                    |
| domDepth          | DOM Depth                     |          | Maximum depth of the DOM tree.                                                                |

## Output

By default, the tool writes a report to `output/wpo.txt` (or the path you specify with `--report`).  
Each metric is compared against its threshold and marked as:

- ✅ Pass
- ⚠️  FAIL (non-critical)
- ❌ FAIL (critical)

Example output:
```
📊 Metrics Evaluation: http://localhost:3000

lcp               :     1.23 (threshold: ≤ 2.5s)         → ✅ Pass
cls               :    0.045 (threshold: ≤ 0.1)          → ✅ Pass
inp               :      180 (threshold: ≤ 200ms)        → ✅ Pass
...
```

If any critical metric fails, the process exits with code `1`.

## License

Copyright © 2025, Adrián Navarro Gabino.
Released under the [MIT License](LICENSE).