Frontend Performance Analyzer — A lightweight CLI tool to analyze frontend performance using Google Lighthouse and Puppeteer.
fpa-cli helps developers quickly audit web pages from the terminal. It runs a headless browser, captures Core Web Vitals, and provides a concise color-coded summary or a full HTML report.
- Automated Audits: Runs Google Lighthouse programmatically via Puppeteer.
- Multi-Device Support: Switch between Mobile (default) and Desktop emulation presets.
- Performance Budgets: Set a threshold score; the CLI will exit with an error if the site fails (perfect for CI/CD pipelines).
- Reliability: Run multiple audits automatically and select the median result to reduce variance.
- Core Web Vitals: Instant checks for LCP, FCP, CLS, TBT, and Speed Index.
- Report Export: Option to save the full Lighthouse HTML report locally.
You can run it directly using npx (recommended) or install it globally.
npx fpa-cli -u https://example.comnpm install -g fpa-cliRun a quick performance check on a URL:
fpa-cli -u https://www.google.comAnalyze the page using desktop screen emulation settings:
fpa-cli -u https://www.google.com --preset desktopFail the build (exit code 1) if the performance score is below 90:
fpa-cli -u https://www.google.com --threshold 90Run the audit 3 times and select the median result to account for network variance:
fpa-cli -u https://www.google.com --runs 3Analyze a URL and save the detailed Lighthouse report to a file:
fpa-cli -u https://github.com -o ./report.html| Option | Alias | Description | Default |
|---|---|---|---|
--url <url> |
-u |
The target URL to analyze | Required |
--output <path> |
-o |
Path to save the full HTML report | null |
--threshold <number> |
-t |
Performance threshold (0-100). Fail if score is below this. | null |
--preset <type> |
-p |
Device preset: mobile or desktop |
mobile |
--runs <number> |
-r |
Number of runs to calculate the median score | 1 |
--no-throttle |
Disable network and CPU throttling | false |
|
--version |
-V |
Output the version number | |
--help |
-h |
Display help for command |
The CLI outputs the following metrics directly to your console:
- Performance Score: Overall Lighthouse performance category score (0-100).
- FCP (First Contentful Paint): When the first text or image is painted.
- LCP (Largest Contentful Paint): Render time of the largest image or text block.
- TBT (Total Blocking Time): Time the main thread was blocked.
- CLS (Cumulative Layout Shift): Visual stability of the page.
- Speed Index: How quickly content is visually displayed.
Contributions are welcome!
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes using Conventional Commits
- Push to the branch
- Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.