Performance Benchmarking - Quick Start

Get up and running with performance benchmarking in minutes.

🚀 First Time Setup

Step 1: Install Lighthouse CI

npm install -g @lhci/cli

This installs the Lighthouse CI tool globally, which is required for running benchmarks.

Step 2: Verify Installation

lhci --version

You should see a version number like 0.13.x.

📊 Running Benchmarks Locally

Full Benchmark Suite

# 1. Build your application
npm run build
 
# 2. Start the production server (in a separate terminal)
npm run start
 
# 3. Wait for server to be ready (you'll see "ready on http://localhost:3000")
 
# 4. In another terminal, run benchmarks
npm run benchmark:lighthouse  # Lighthouse metrics
npm run benchmark:bundle      # Bundle size
npm run benchmark:memory      # Memory usage
 
# 5. Parse results and generate report
npm run benchmark:parse
npm run benchmark:report
 
# 6. Check against budgets
npm run benchmark:check

Quick Bundle Analysis (No server needed)

# Just analyze bundle size after building
npm run build
npm run analyze:bundle

🎯 What Each Command Does

📈 Viewing Results

Console Output

All commands print results to the console:

npm run benchmark:check

Output:

💰 Performance Budget Check

Budget Status:
  ✅ First Contentful Paint         1245ms       (budget: 1800ms)
  ✅ Largest Contentful Paint       1876ms       (budget: 2500ms)
  ✅ Cumulative Layout Shift        0.05         (budget: 0.1)
  ...

JSON Reports

Results are saved in benchmark-results/:

• lighthouse-results.json - Full Lighthouse data
• bundle-size.json - Bundle analysis
• memory-benchmark.json - Memory metrics
• performance-report.json - Combined report

HTML Reports

Lighthouse generates HTML reports in .lighthouse-benchmark/:

# Open in browser
start .lighthouse-benchmark/*/lhr-*.html

⚠️ Troubleshooting

Error: 'lhci' is not recognized

Problem: Lighthouse CI not installed globally

Solution:

npm install -g @lhci/cli

Error: startServerCommand failed

Problem: Server isn't starting or listening on port 3000

Solution:

1. Make sure you've built the app: npm run build
2. Manually start the server in another terminal: npm run start
3. Wait for "ready on http://localhost:3000 (opens in a new tab)"
4. Run npm run benchmark:lighthouse in the first terminal

Error: Navigation timeout

Problem: Server is slow to respond or pages don't exist

Solution:

1. Check that all URLs in lighthouserc.benchmark.json exist
2. Increase timeout in config if needed
3. Make sure server is running in production mode

Zero Metrics (0ms, 0/100)

Problem: Benchmarks haven't been run yet

Solution:

# Full sequence
npm run build
npm run start  # in another terminal
npm run benchmark:lighthouse
npm run benchmark:parse
npm run benchmark:report
npm run benchmark:check

🎯 Performance Budgets

Current budgets (edit in scripts/check-performance-budget.js):

🔄 Automated Monitoring (CI/CD)

Benchmarks run automatically in GitHub Actions:

• ✅ On every push to main
• ✅ On every PR to main/develop
• ✅ Daily at 2 AM UTC
• ✅ Manual workflow dispatch

No local setup needed for CI/CD - it runs automatically!

💡 Tips

For Development

# Quick bundle check during development
npm run build
npm run analyze:bundle

Before Committing

# Verify performance hasn't regressed
npm run build
npm run start  # separate terminal
npm run benchmark:lighthouse
npm run benchmark:check

For CI/CD Testing

# Simulate what runs in GitHub Actions
npm run build
npm run benchmark
npm run benchmark:parse
npm run benchmark:report
npm run benchmark:check

📚 More Information

For detailed documentation, see:

• Performance Benchmarking Guide - Complete guide
• .github/workflows/performance-benchmark.yml - GitHub Actions workflow

✅ Quick Checklist

First time setup:

• Install Lighthouse CI: npm install -g @lhci/cli
• Verify installation: lhci --version

Before running benchmarks:

• Build the app: npm run build
• Start the server: npm run start (separate terminal)
• Wait for server ready message

Run benchmarks:

• npm run benchmark:lighthouse
• npm run benchmark:parse
• npm run benchmark:report
• npm run benchmark:check

Review results:

• Check console output
• Review benchmark-results/*.json
• Open HTML reports (optional)

🎉 You're all set! The framework maintains 100/100 Lighthouse scores with automated monitoring.