Performance

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.

In sintesi

  • lighthouserc.json dichiara le assert e trasforma una soglia in un test che blocca il merge.
  • numberOfRuns a 3 fa confrontare la mediana, non una singola esecuzione.
  • Un budget verde in CI non garantisce un passaggio nei dati di campo.

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.

Tre tipi di soglia

TipoEsempioEffetto
Metricalargest-contentful-paint ≤ 2500errore, blocca il merge
Peso totaletotal-byte-weight ≤ 500000errore sul budget di pagina
Terze partithird-party-summaryavviso, da rivedere

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

  • Blocca solo metriche stabili: LCP e CLS come errore, TBT come avviso.
  • Fissa il budget byte sulla pagina di articolo, non sulla home, perché è quella che si legge.
  • Ripeti la misura tre volte e confronta la mediana: un run isolato non è una regressione.

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.

Domande frequenti

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.