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
  • Options
• Configuration
  • Properties
• Thresholds
• Output
• License

Installation and Usage

Prerequisites: Node.js (^20.19.2).

Note: It is recommended to use Node Version Manager (nvm).

You can run WPO Check on any url like this:

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:

{
  "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:

{
  "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.