154 lines
4.4 KiB
Markdown
154 lines
4.4 KiB
Markdown
# Lighthouse Testing Guide
|
|
|
|
This guide explains how to test Lighthouse performance scores locally and achieve 100% scores across all categories.
|
|
|
|
## Prerequisites
|
|
|
|
1. Install dependencies:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
npm install -g @lhci/cli
|
|
```
|
|
|
|
2. Run CI tests:
|
|
```bash
|
|
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](https://developers.google.com/web/tools/lighthouse)
|
|
- [Next.js Image Optimization](https://nextjs.org/docs/app/api-reference/components/image)
|
|
- [Core Web Vitals](https://web.dev/vitals/)
|
|
- [Web Performance Best Practices](https://web.dev/performance/)
|