Rocky_Mountain_Vending/LIGHTHOUSE_TESTING.md

Lighthouse Testing Guide

This guide explains how to test Lighthouse performance scores locally and achieve 100% scores across all categories.

Prerequisites

1. Install dependencies:

   npm install
   # or
   pnpm install
   

2. Ensure Chrome/Chromium is installed (required for Lighthouse CLI)

Running Lighthouse Tests

Test Production Build (Recommended)

This is the most accurate way to test Lighthouse scores, as it tests the actual production-optimized bundle:

npm run lighthouse:build

This command will:

1. Build the production bundle (next build)
2. Start the production server (next start)
3. Run Lighthouse tests on multiple pages
4. Display scores and metrics
5. Stop the server automatically

Test Dev Server (Less Accurate)

For quick testing during development (less accurate scores):

npm run lighthouse:dev

Note: Dev server scores are typically lower than production scores due to unoptimized code and development overhead.

Understanding the Results

Score Categories

Lighthouse tests four main categories, each scored 0-100:

• Performance: Measures page load speed and Core Web Vitals
• Accessibility: Checks for accessibility best practices
• Best Practices: Validates modern web development practices
• SEO: Evaluates search engine optimization

Core Web Vitals

The script also reports these critical metrics:

• FCP (First Contentful Paint): Time until first content appears (target: < 1.8s)
• LCP (Largest Contentful Paint): Time until main content loads (target: < 2.5s)
• CLS (Cumulative Layout Shift): Visual stability measure (target: < 0.1)
• TBT (Total Blocking Time): Time page is blocked from interaction (target: < 200ms)
• SI (Speed Index): How quickly content is visually displayed (target: < 3.4s)

Target Scores

For 100% scores, all categories must achieve:

• Performance: 100/100
• Accessibility: 100/100
• Best Practices: 100/100
• SEO: 100/100

Performance Optimizations Implemented

Image Optimization

• Next.js Image optimization enabled (unoptimized: false)
• Automatic WebP/AVIF format conversion
• Responsive image sizes
• Proper width/height attributes to prevent layout shift
• Lazy loading for below-the-fold images

Third-Party Scripts

• LeadConnector script loaded with afterInteractive strategy
• Resource hints (preconnect/dns-prefetch) for external domains
• Scripts don't block initial page render

Caching Headers

• Static assets cached for 1 year
• Images cached with immutable flag
• Fonts cached for optimal performance

Bundle Optimization

• Code splitting enabled
• Tree shaking for unused code
• Bundle analyzer available (npm run analyze)

Troubleshooting

Low Performance Scores

1. Check image optimization: Ensure images are using Next.js Image component
2. Verify production build: Always test production builds, not dev server
3. Check bundle size: Run npm run analyze to identify large dependencies
4. Review third-party scripts: Ensure they're loaded asynchronously

Images Not Optimizing

If images aren't being optimized:

• Ensure unoptimized: false in next.config.mjs
• Check that images are using Next.js Image component, not <img> tags
• Verify image domains are in remotePatterns if using external images

Layout Shift Issues

• Ensure all images have explicit width and height attributes
• Use fill prop with aspect-ratio containers for responsive images
• Avoid dynamic content that changes layout after load

Continuous Integration

The .lighthouserc.js file is configured for Lighthouse CI. To use it:

1. Install Lighthouse CI:

   npm install -g @lhci/cli
   

2. Run CI tests:

   npm run lighthouse:ci
   

Best Practices

1. Always test production builds: Dev server scores are not representative
2. Test multiple pages: Different pages may have different performance characteristics
3. Monitor Core Web Vitals: These directly impact user experience and SEO
4. Regular testing: Run Lighthouse tests before deploying major changes
5. Bundle analysis: Regularly check bundle size with npm run analyze

Additional Resources

• Lighthouse Documentation
• Next.js Image Optimization
• Core Web Vitals
• Web Performance Best Practices