When to Use
- Post-deploy performance regression detection: Run a Lighthouse audit on each deployment and compare the performance score to the previous run. Trigger an alert or block the deploy if the score drops below a threshold.
- Scheduled site health monitoring: Run daily or weekly audits on critical marketing pages and store results in a database for trend analysis.
- SEO compliance checks: Integrate Lighthouse SEO score checks into content approval workflows — flag pages with SEO scores below the organisation's minimum before publishing.
- Accessibility compliance reporting: Audit published pages against accessibility targets and generate reports for compliance teams on a scheduled cadence.
- Vendor and partner SLA monitoring: Audit externally hosted pages (partner integrations, embedded widgets) and alert if their performance degrades below agreed thresholds.
Timeout: Lighthouse audits typically take 30–120 seconds depending on page complexity and network conditions. The node applies a dedicated timeout for this operation — set timeout to at least 120000 (120 s) for reliable results on complex pages.
Configuration
Connection
| Field | Required | Description |
|---|
BaseUrl | Required | Browserless instance URL. |
Token | Optional | API token for cloud Browserless. |
Operation
| Field | Required | Description |
|---|
url | Required | The page URL to audit. Supports BizFirst expressions. |
config | Optional | Lighthouse configuration object. Controls which audits run, device emulation (formFactor: "desktop" or "mobile"), throttling settings, and locale. See the Lighthouse config docs for all options. |
budgets | Optional | Array of Lighthouse performance budget objects. When provided, Lighthouse compares audit results against these budgets and includes budget warnings in the report. |
blockAds | Optional | Default true. Block ad networks during the audit. Disabling this measures the real-world impact of ads on performance. |
timeout | Optional | Request timeout in milliseconds. Recommended minimum: 120000. The node applies a dedicated timeout cancellation token for this operation. |
useCustomBody | Optional | Send customBodyJson verbatim as the request body. |
customBodyJson | Optional | Raw JSON body when useCustomBody is true. |
Sample Configuration
{
"operation": "performance",
"baseUrl": "https://chrome.browserless.io",
"token": "{{ $env.BROWSERLESS_TOKEN }}",
"url": "https://www.example.com/landing/{{ $input.slug }}",
"config": {
"formFactor": "desktop",
"screenEmulation": {
"mobile": false,
"width": 1350,
"height": 940,
"deviceScaleFactor": 1,
"disabled": false
},
"throttling": {
"rttMs": 40,
"throughputKbps": 10240,
"cpuSlowdownMultiplier": 1
}
},
"timeout": 120000,
"blockAds": false
}
Validation Errors
| Error Code | Cause |
|---|
VAL_MISSING_URL | url is empty. |
CFG_INVALID | Node settings could not be resolved to a performance configuration. |
TIMEOUT | The Lighthouse audit exceeded the configured timeout. Increase timeout or simplify the audit configuration. |
BROWSERLESS_BAD_REQUEST | customBodyJson is not valid JSON or does not match the performance request shape. |
Output
Success Port
| Field | Type | Description |
|---|
status | string | Always "success". |
errorCode | string | Always empty on success. |
operation | string | Always "performance". |
url | string | URL that was audited. |
performanceScore | number | Lighthouse Performance category score (0–1). Multiply by 100 for the familiar 0–100 display value. |
accessibilityScore | number | Lighthouse Accessibility category score (0–1). |
seoScore | number | Lighthouse SEO category score (0–1). |
bestPracticesScore | number | Lighthouse Best Practices category score (0–1). |
report | object | Full Lighthouse report JSON object. Contains all audit results, metrics (LCP, FID, CLS, FCP, TTI, TBT), opportunities, diagnostics, and budget results. |
Error Port
| Field | Type | Description |
|---|
status | string | Always "error". |
errorCode | string | Machine-readable error code (e.g. TIMEOUT, BROWSERLESS_BAD_REQUEST). |
errorMessage | string | Human-readable failure description. |
operation | string | Always "performance". |
httpStatusCode | int | HTTP status code from Browserless, if available. |
Sample Output
{
"status": "success",
"errorCode": "",
"operation": "performance",
"url": "https://www.example.com/landing/summer-promo",
"performanceScore": 0.94,
"accessibilityScore": 0.88,
"seoScore": 0.97,
"bestPracticesScore": 0.83,
"report": {
"lighthouseVersion": "11.3.0",
"requestedUrl": "https://www.example.com/landing/summer-promo",
"finalUrl": "https://www.example.com/landing/summer-promo",
"fetchTime": "2026-05-26T09:12:34.000Z",
"categories": {
"performance": { "score": 0.94, "title": "Performance" },
"accessibility": { "score": 0.88, "title": "Accessibility" },
"best-practices": { "score": 0.83, "title": "Best Practices" },
"seo": { "score": 0.97, "title": "SEO" }
},
"audits": {
"first-contentful-paint": { "numericValue": 980, "displayValue": "1.0 s" },
"largest-contentful-paint": { "numericValue": 2100, "displayValue": "2.1 s" },
"total-blocking-time": { "numericValue": 45, "displayValue": "45 ms" },
"cumulative-layout-shift": { "numericValue": 0.01, "displayValue": "0.01" },
"speed-index": { "numericValue": 1340, "displayValue": "1.3 s" }
}
}
}
Expression Reference
| Expression | Value |
|---|
{{ $output.BrowserlessNode.performanceScore }} | Performance score 0–1 (e.g. 0.94). |
{{ $output.BrowserlessNode.accessibilityScore }} | Accessibility score 0–1. |
{{ $output.BrowserlessNode.seoScore }} | SEO score 0–1. |
{{ $output.BrowserlessNode.bestPracticesScore }} | Best Practices score 0–1. |
{{ $output.BrowserlessNode.report }} | Full Lighthouse report object. |
{{ $output.BrowserlessNode.report.audits['largest-contentful-paint'].numericValue }} | LCP in milliseconds. |
{{ $output.BrowserlessNode.report.audits['cumulative-layout-shift'].numericValue }} | CLS score. |
{{ $output.BrowserlessNode.url }} | URL that was audited. |
Node Policies & GuardRails
| Policy | Recommendation | Severity |
|---|
| Timeout configuration | Always set timeout to at least 120 s. Lighthouse audits on complex pages commonly take 60–90 s and will produce TIMEOUT errors with shorter limits. | High |
| Token storage | Store the API token in a workflow secret. | Critical |
| Report object size | The full Lighthouse report can exceed 1 MB. Extract only the scores and metrics you need via expression mappings rather than persisting the entire report to a database. | Medium |
| Score variance | Lighthouse scores vary between runs (±5 points is normal) due to CPU throttling simulation. Run 3 audits and average the scores for more stable trend data. | Medium |
| URL validation | Validate and allowlist target domains before auditing user-supplied URLs. | High |
Examples
Example 1 — Daily performance monitoring with Slack alert
Audit the homepage at 07:00 daily and send a Slack message if performance drops below 0.85.
{
"operation": "performance",
"baseUrl": "https://chrome.browserless.io",
"token": "{{ $env.BROWSERLESS_TOKEN }}",
"url": "https://www.example.com/",
"config": {
"formFactor": "mobile",
"screenEmulation": { "mobile": true, "width": 390, "height": 844, "deviceScaleFactor": 3 }
},
"timeout": 120000,
"blockAds": false
}
Example 2 — Desktop audit with budget constraints
{
"operation": "performance",
"baseUrl": "https://chrome.browserless.io",
"token": "{{ $env.BROWSERLESS_TOKEN }}",
"url": "{{ $input.pageUrl }}",
"config": { "formFactor": "desktop" },
"budgets": [
{
"path": "/*",
"timings": [
{ "metric": "first-contentful-paint", "budget": 2000 },
{ "metric": "largest-contentful-paint", "budget": 3000 }
],
"resourceSizes": [
{ "resourceType": "script", "budget": 500 },
{ "resourceType": "image", "budget": 1000 },
{ "resourceType": "total", "budget": 2000 }
]
}
],
"timeout": 120000
}
Example 3 — Post-deploy regression check
Triggered by a deployment webhook — compares the new score to a stored baseline and fails the workflow if performance regressed by more than 5 points.
{
"operation": "performance",
"baseUrl": "https://chrome.browserless.io",
"token": "{{ $env.BROWSERLESS_TOKEN }}",
"url": "https://staging.example.com{{ $input.path }}",
"config": { "formFactor": "desktop" },
"timeout": 150000,
"blockAds": true
}
