# Lighthouse CI with budgets: assertions that block a merge

A lighthouserc.json with numberOfRuns, assertions on LCP, CLS and TBT, and byte budgets: the setup that blocks a merge when the site gets slower.

> Page: https://ui.eneawork.it/blog/come-usare-lighthouse-ci
> Markdown: https://ui.eneawork.it/blog/come-usare-lighthouse-ci.md

*2026-11-01*

Risposta breve: installa @lhci/cli, descrivi URL e soglie in lighthouserc.json e lancia lhci autorun in CI. Se un'asserzione error non passa, il job si ferma e il merge non entra.

Nella settimana 23-29 ottobre 2026 @lhci/cli ha totalizzato 2.435.693 download e lighthouse 6.886.044, letti da api.npmjs.org il 1 novembre 2026; le versioni correnti sono 0.15.1 e 13.6.0. Lighthouse è Apache 2.0. Il catalogo EneUI misura 111.985 componenti, 1.556 blocchi e 12.808 icone da 1.472 librerie, misurati da /api/stats il 1 novembre 2026.

## Installare e lanciare una volta a mano

npm i -D @lhci/cli@0.15 npx lhci autorun --collect.url=http://localhost:3000/

autorun fa tre passi: collect avvia Chrome headless e salva i report, assert confronta i numeri con le soglie, upload pubblica l'esito. Il primo giro serve a vedere i numeri veri prima di scegliere le soglie.

## Il file di configurazione

{ "ci": { "collect": { "url": ["http://localhost:3000/"], "numberOfRuns": 3 }, "assert": { "assertions": { "categories:performance": ["error", { "minScore": 0.9 }], "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }], "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }], "total-blocking-time": ["error", { "maxNumericValue": 200 }] } }, "upload": { "target": "temporary-public-storage" } } }

numberOfRuns: 3 esegue Lighthouse tre volte e tiene la mediana: è il rimedio alla varianza di un runner condiviso. Le soglie 2.500 ms, 0,1 e 200 ms sono quelle pubblicate da web.dev per LCP, CLS e TBT.

## error, warn e il resto

Un'asserzione error fa terminare il job, warn stampa e prosegue. Comincia con warn su un progetto già in produzione e passa a error dopo aver portato i numeri sotto soglia: un budget che blocca il team dal primo giorno viene disattivato in una settimana.

## Budget in byte, non solo punteggi

{ "ci": { "assert": { "assertions": { "resource-summary:script:size": ["error", { "maxNumericValue": 180000 }], "resource-summary:total:size": ["error", { "maxNumericValue": 600000 }] } } } }

Le asserzioni resource-summary contano i byte trasferiti per tipo di risorsa. Sono più stabili dei punteggi, perché non dipendono dalla velocità del runner: un budget sui byte cambia quando cambia il codice.

## Limite dichiarato

Lighthouse CI misura in laboratorio con throttling simulato: non sostituisce i dati di campo di CrUX, che arrivano dagli utenti reali. Un punteggio 100 non garantisce un LCP sotto 2,5 s su un telefono lento.

## Dove continuare

Nel catalogo trovi la card con metrica, il grafico a ciambella e i blocchi della categoria chart. Per il resto leggi le soglie di Lighthouse CI spiegate, la guida a PerformanceObserver e il confronto analytics Vercel o self-hosted.

## FAQ

### Lighthouse CI è lo stesso strumento di Lighthouse?

Sì. @lhci/cli orchestra Lighthouse: collect avvia le esecuzioni, assert confronta i risultati, upload conserva i report. Il motore di misura è lo stesso.

### Quante esecuzioni servono per un risultato stabile?

Tre è il minimo pratico, cinque su un runner molto variabile. Lighthouse CI usa la mediana delle esecuzioni, quindi un singolo valore anomalo non decide l'esito.

### Devo ospitare un server per i report?

No. Con upload target temporary-public-storage i report restano disponibili per pochi giorni su uno spazio pubblico. Per la cronologia serve un server LHCI, che è un progetto a parte.

### Posso bloccare solo le regressioni, non i valori assoluti?

Sì, è la configurazione più utile su un progetto già lento: confronti la build corrente con la precedente e fissi una tolleranza. Le asserzioni su valori assoluti servono dopo aver portato i numeri sotto soglia.

### Lighthouse CI misura anche su mobile reale?

No. Emula un telefono con CPU e rete rallentate dentro Chrome headless: utile per confrontare build, non per stimare l'esperienza su un dispositivo specifico.