frontend-lighthouse

name	frontend-lighthouse
description	Adds a portable Lighthouse CI gate: lighthouserc.cjs Core Web Vitals budgets (LCP, CLS, TBT), category floors, median-of-N runs, and GitHub Actions artifacts against the production build. Use when adding performance gates, setting CWV budgets, or debugging flaky LHCI. Not for one-off DevTools audits on a Vite/Next dev server, motion-craft review (review-animations), or raising budgets instead of fixing the report.
version	1.0.1
category	frontend
risk	safe
source	community
source_repo	stareezy-1/frontend-architecture-skill
source_type	community
date_added	2026-06-29
tags	["frontend","lighthouse","performance","core-web-vitals","ci"]
tools	["lighthouse","node","github-actions"]
license	MIT
license_source	https://github.com/stareezy-1/frontend-architecture-skill/blob/main/LICENSE

Overview

This skill describes a CI performance gate — a Lighthouse CI config plus a workflow — not a component library or a visual style. It pairs with the frontend-seo and frontend-architecture skills: SEO writes the metadata, Lighthouse proves it ships fast.

The goal: every pull request is blocked unless the production build meets explicit Core Web Vitals budgets and category score floors. Budgets live in one lighthouserc.cjs, runs are median-of-N so the gate doesn't flake, and the same config runs locally and in CI.

When to Use

• Use when adding a Lighthouse CI performance gate to a web app.
• Use when setting Core Web Vitals budgets for LCP, CLS, and TBT as the lab proxy for INP.
• Use when configuring category score floors for performance, SEO, accessibility, and best practices.
• Use when debugging flaky Lighthouse runs or making reports visible as CI artifacts.

Prerequisites

• Node.js 22 (match the repo's pinned version to avoid lockfile drift)
• pnpm (or npm/yarn)
• @lhci/cli installed as a dev dependency

Procedure

1. Install the Lighthouse CLI

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

2. Create the Lighthouse Config

Create lighthouserc.cjs at your app root (e.g., apps/web/lighthouserc.cjs). Use .cjs (CommonJS) so it loads without ESM/TS transpilation. Every budget must be a named constant with a comment explaining the threshold — never a bare number inside an assertion.

/**
 * Lighthouse CI configuration — Core Web Vitals budgets for the marketing surface.
 *
 * Enforces Google's mobile "good" CWV thresholds:
 *   - Largest Contentful Paint (LCP) ≤ 2500 ms
 *   - Cumulative Layout Shift (CLS)  ≤ 0.1
 *   - Interaction to Next Paint (INP) ≤ 200 ms
 *
 * INP is a *field* metric with no direct lab audit, so in the lab we gate on
 * Total Blocking Time (TBT) — Lighthouse's recommended lab proxy — at the same
 * budget, and assert the experimental INP audit directly as a warning where the
 * build exposes it.
 *
 * Collection runs against the *production* server (build + start) on Lighthouse's
 * default mobile (Moto G4 / slow 4G) emulation.
 */

/** The fixed port the production server is started on for the audit. */
const  = ;
  = ;


  = [];


  = ; 
  = ; 
  = ; 

. = {
  : {
    : {
      
      : ,
      : , 
      : ,
      : ,
      
      : ,
      : {
        
        :
          process.. ===  ?  : ,
        
        : [
          ,
          ,
          ,
          ,
        ],
      },
    },
    : {
      
      : ,
      : {
        
        : [
          ,
          { :  },
        ],
        : [, { :  }],
        : [, { :  }],
        
        : [
          ,
          { :  },
        ],

        
        : [, { :  }],
        : [, { :  }],
        : [, { :  }],
        : [, { :  }],
      },
    },
    : {
      
      : ,
      : ,
    },
  },
};