# Lighthouse CI con soglie: budget che bloccano il merge

Lighthouse CI trasforma LCP, CLS e peso dei file in assert che fanno fallire la build. Configurazione, comando e soglie che non producono rumore.

> Pagina: https://ui.eneawork.it/blog/lighthouse-ci-soglie
> Markdown: https://ui.eneawork.it/blog/lighthouse-ci-soglie.md

*2026-11-01*

Lighthouse CI trasforma le soglie in un test che blocca il merge: dichiari i limiti in lighthouserc.json e la build fallisce quando una misura scende sotto. Senza quel file un budget resta un proposito.

Abbiamo misurato la build EneUI del 1 novembre 2026: 64 file in client/dist/assets per 661.990 byte totali, 47 dei quali JavaScript; index.html pesa 22.933 byte e il chunk vendor 141.671. Il catalogo EneUI misura 111.985 componenti, 1.556 blocchi e 12.808 icone da 1.472 librerie, letti da /api/stats il 1 novembre 2026. I nomi delle assert vengono dalla documentazione Lighthouse CI di Google, licenza Apache 2.0. Nel repository non esiste ancora un file lighthouserc: i numeri qui sotto sono la base per scriverlo.

## Tre tipi di soglia

## Il file

{ "ci": { "collect": { "url": ["https://ui.eneawork.it/"], "numberOfRuns": 3 }, "assert": { "assertions": { "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }], "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }], "total-byte-weight": ["error", { "maxNumericValue": 500000 }] } } } }

La chiave numberOfRuns a 3 fa calcolare la mediana: una singola esecuzione cambia troppo per essere una soglia affidabile.

## Il comando

npx --yes @lhci/cli autorun

Il comando avvia Chrome, esegue tre run sull'URL dichiarato e confronta i risultati con le assert. Senza la sezione upload non invia nulla a un server esterno.

## Soglie che non producono rumore

## Cosa Lighthouse non misura

INP non esiste in laboratorio: Lighthouse misura TBT come sostituto e lascia il giudizio ai dati di campo. Un budget verde in CI non garantisce un passaggio nel Chrome UX Report.

## La limitazione

Questo repository non ha ancora un file lighthouserc: oggi nessun job blocca un aumento di peso. I numeri misurati qui servono a fissare il primo budget, non a dichiarare un risultato.

## Dove continuare

Il catalogo EneUI indicizza 111.985 componenti e 1.556 blocchi con preview. Il blocco hero è la sezione che decide il LCP di una landing: misuralo prima di sceglierlo. Per le soglie leggi Core Web Vitals, per il peso delle librerie il bundle di una UI library, per il confronto misurato librerie React 2026.

## FAQ

### Lighthouse CI blocca davvero il merge?

Sì, se il job esce con codice diverso da zero: GitHub Actions e GitLab leggono il codice e segnano la pipeline come fallita. Serve però una regola di branch protection che richieda quel job.

### Quante esecuzioni servono?

Tre è il minimo pratico: Lighthouse CI calcola la mediana e ignora un run rumoroso. Con una sola esecuzione la soglia produce falsi rossi.

### Posso usare le soglie sui punteggi?

Puoi, ma i punteggi cambiano molto tra run e tra versioni. Le soglie sulle metriche numeriche, come LCP in millisecondi, sono più stabili e più facili da spiegare.

### Funziona su un sito dietro login?

Sì, con uno script di Puppeteer che compila il form prima della misura. Il budget va applicato alla pagina autenticata, non alla schermata di accesso.

### Differenza tra budget e assert?

Il budget è il numero che dichiari, l'assert è la regola che lo applica. Un budget senza assert è documentazione; un assert senza budget è una soglia inventata.