Lighthouse Frontend (portão de desempenho portátil)

Habilidade portátil — legível por Claude Code, OpenCode, Codex, Cursor, Windsurf e outros. Esta habilidade descreve um portão de desempenho em CI — uma configuração do Lighthouse CI mais um fluxo de trabalho — não uma biblioteca de componentes ou um estilo visual. Ela se associa às habilidades frontend-seo e frontend-architecture: SEO escreve os metadados, Lighthouse prova que entrega rápido.

O objetivo: cada pull request é bloqueado a menos que a build de produção atenda a orçamentos explícitos de Core Web Vitals e pisos de pontuação de categoria. Os orçamentos vivem em um lighthouserc.cjs, as execuções são mediana de N para que o portão não falhe, e a mesma configuração é executada localmente e em CI.

Quando Usar Esta Habilidade

• Use ao adicionar um portão de desempenho do Lighthouse CI a um aplicativo web.
• Use ao definir orçamentos de Core Web Vitals para LCP, CLS e TBT como proxy de laboratório para INP.
• Use ao configurar pisos de pontuação de categoria para desempenho, SEO, acessibilidade e melhores práticas.
• Use ao depurar execuções instáveis do Lighthouse ou tornar relatórios visíveis como artefatos de CI.

0. As cinco ideias centrais

1. Uma configuração, uma fonte de verdade. Todos os orçamentos e asserções vivem em um único lighthouserc.cjs. Constantes nomeadas para cada orçamento — sem números mágicos escondidos em objetos de asserção.
2. Bloqueie a build de produção, nunca o desenvolvimento. O Lighthouse executa contra build + start (a saída real e otimizada). Números do servidor de desenvolvimento são sem sentido para um orçamento.
3. Mediana de N elimina a instabilidade. Execute 3+ vezes e afirme sobre a execução mediana, para que o jitter por execução (caches frios, ruído de CI) nunca sinalize uma build saudável.
4. Orçamentos codificam os limites "bons" do Google. LCP ≤ 2500 ms, INP ≤ 200 ms (bloqueado via proxy de laboratório TBT), CLS ≤ 0.1 — os valores que ganham pontuações verdes, não "precisa de melhoria".
5. Bloqueio em CI, visível como artefatos. Uma GitHub Action executa o portão em cada PR que toca o aplicativo e carrega os relatórios HTML/JSON para que falhas sejam depuráveis.

1. Arquivos que esta habilidade adiciona

apps/web/                          (or your app root)
├── lighthouserc.cjs               ← the gate: budgets + assertions + collect settings
├── package.json                   ← "lhci": "lhci autorun --config=./lighthouserc.cjs"
└── .github/workflows/lighthouse.yml  ← PR-blocking CI job (build → start → lhci → upload)

Mais uma dependência de desenvolvimento: @lhci/cli.

pnpm add -D @lhci/cli        # or npm i -D / yarn add -D

2. A configuração (lighthouserc.cjs)

.cjs (CommonJS) para carregar sem transpilação ESM/TS. Cada orçamento é uma constante nomeada com um comentário explicando o limite — nunca um número bruto dentro de um objeto de asserção.

/**
 * Configuração do Lighthouse CI — Orçamentos de Core Web Vitals para a superfície de marketing.
 *
 * Aplica os limites "bons" de CWV para dispositivos móveis do Google:
 *   - Largest Contentful Paint (LCP) ≤ 2500 ms
 *   - Cumulative Layout Shift (CLS)  ≤ 0.1
 *   - Interaction to Next Paint (INP) ≤ 200 ms
 *
 * INP é uma métrica de *campo* sem auditoria direta de laboratório, então no laboratório bloqueamos
 * o Total Blocking Time (TBT) — o proxy de laboratório recomendado pelo Lighthouse — com o mesmo
 * orçamento, e afirmamos a auditoria experimental de INP diretamente como um aviso onde
 * a build a expõe.
 *
 * A coleta é executada contra o servidor de *produção* (build + start) na emulação
 * móvel padrão do Lighthouse (Moto G4 / 4G lento).
 */

/** A porta fixa em que o servidor de produção é iniciado para a auditoria. */
const PORT = 3100;
const BASE_URL = `http://localhost:${PORT}`;

/** Páginas cujos orçamentos são aplicados em CI. */
const MARKETING_URLS = [`${BASE_URL}/`];

/**
 * Orçamentos de Core Web Vitals em dispositivos móveis — limites "bons" do Google.
 * Estes são os valores que obtêm as melhores pontuações do Lighthouse.
 */
const LCP_BUDGET_MS = 2500; // bom
const INP_BUDGET_MS = 200; // bom (proxy de laboratório TBT)
const CLS_BUDGET = 0.1; // bom

module.exports = {
  ci: {
    collect: {
      // A build é executada separadamente em CI; aqui apenas servimos a saída de produção.
      startServerCommand: `pnpm start --port ${PORT}`,
      startServerReadyPattern: "Ready in", // linha de log "servidor pronto" do framework
      startServerReadyTimeout: 120000,
      url: MARKETING_URLS,
      // Mediana de múltiplas execuções mantém o portão estável contra jitter por execução.
      numberOfRuns: 3,
      settings: {
        // Emulação móvel padrão; opte por desktop via env para uma segunda execução.
        preset:
          process.env.LHCI_FORM_FACTOR === "desktop" ? "desktop" : undefined,

…