@lhci/cli

The Lighthouse CI CLI is a powerful tool for automating performance monitoring in CI/CD pipelines. The core workflow is straightforward: collect Lighthouse reports, upload them, and assert against budgets. The configuration file (lighthouserc.json) is well-structured and the assert/upload commands work reliably once configured.

The documentation covers most use cases, but the initial setup requires piecing together examples from different sections. The error messages during assertion failures are clear and actionable, showing you exactly which metrics failed and by how much. The autorun command is particularly convenient for simple setups, handling collection and assertions in one step.

Type definitions are available but minimal - mostly for configuration objects. IDE support is adequate for the config file structure, though you'll reference docs frequently for advanced options. The wizard command helps with initial setup, but you'll likely need to manually tweak the generated config. Integration with GitHub Actions and other CI providers is well-documented with working examples.

Running Lighthouse CI in production pipelines is straightforward with sensible defaults. The CLI handles Chrome management reasonably well, though you'll want to monitor memory usage during parallel runs - each Lighthouse instance can spike to 500MB+. The autorun command is convenient but you'll quickly graduate to granular collect/upload/assert commands for better control over retry logic and resource cleanup.

Configuration via lighthouserc.json is flexible but watch out for timeout defaults - the default 60s can be too aggressive for slower environments. The assertion system is powerful for catching performance regressions, though error messages when budgets fail could be more actionable. Logging is adequate but basic; you'll want to wrap calls with your own instrumentation for proper observability in CI/CD.

Resource cleanup is generally reliable, but zombie Chrome processes occasionally survive failed runs. The server upload functionality works well once configured, though connection pooling isn't exposed for tuning. Breaking changes between 0.x versions have been minimal, making upgrades relatively painless.

Setting up LHCI was surprisingly straightforward with the official getting started guide. The wizard (`lhci wizard`) helps generate initial configuration, which saves time. Running Lighthouse audits in CI pipelines works reliably once configured, and the assertions system lets you set performance budgets that actually fail builds when metrics regress.

The documentation covers most common scenarios well, with clear examples for different CI providers. However, the configuration options can be overwhelming initially—there are many ways to configure the same thing (lighthouserc.js vs lighthouserc.json vs CLI flags), and it's not always obvious which takes precedence. Error messages when URLs fail or assertions break are generally helpful, showing exactly which metric failed and by how much.

Debugging can be challenging when dealing with authentication or dynamic pages. The `--debug` flag helps, but you often need to experiment with puppeteer script options. GitHub issues get responses, though not always quickly. Stack Overflow coverage is thin, so you'll rely heavily on official docs and issue threads.