# Web Vitals Integration Checklist Use this checklist to verify your Web Vitals implementation is complete and working correctly. ## Pre-Integration - [ ] `web-vitals` package is installed (already done - v5.1.0) - [ ] Sentry is configured in the project - [ ] You have a Sentry DSN available ## Implementation Files - [x] `lib/monitoring/web-vitals.ts` - Core implementation (273 lines) - [x] `lib/monitoring/index.ts` - Clean exports - [x] `app/components/WebVitalsReporter.tsx` - Integration component - [x] `__tests__/lib/monitoring/web-vitals.test.ts` - Test suite (15 tests) - [x] `lib/monitoring/README.md` - API documentation - [x] `lib/monitoring/INTEGRATION.md` - Integration guide ## Code Quality - [x] All 6 metrics tracked (LCP, FID, CLS, TTFB, FCP, INP) - [x] Sentry integration (measurements, breadcrumbs, warnings) - [x] Performance thresholds defined (good/needs-improvement/poor) - [x] Google Analytics 4 support - [x] TypeScript types complete - [x] Error handling for missing dependencies - [x] SSR-safe implementation - [x] Development logging ## Testing - [x] Test suite created (8 suites, 15 test cases) - [ ] Tests pass: `npm test -- __tests__/lib/monitoring/web-vitals.test.ts` - [ ] No TypeScript errors: `npx tsc --noEmit` - [ ] No lint errors: `npm run lint` ## Integration ### Step 1: Environment Setup - [ ] Set `NEXT_PUBLIC_SENTRY_DSN` in `.env.local` - [ ] Verify Sentry client config exists (`sentry.client.config.ts`) ### Step 2: Add to Layout - [ ] Import `WebVitalsReporter` in `app/layout.tsx` - [ ] Add `` component to layout Example: ```tsx import { WebVitalsReporter } from './components/WebVitalsReporter'; export default function RootLayout({ children }) { return ( {children} ); } ``` ### Step 3: Development Testing - [ ] Run `npm run dev` - [ ] Open http://localhost:9000 - [ ] Check browser console for Web Vitals logs - [ ] Verify logs show: `[Web Vitals] { name: 'LCP', value: ..., rating: ... }` ### Step 4: Sentry Verification - [ ] Navigate your app to trigger metrics - [ ] Open Sentry dashboard - [ ] Go to Performance → Web Vitals - [ ] Verify metrics appear for: - [ ] LCP (Largest Contentful Paint) - [ ] FID (First Input Delay) - [ ] CLS (Cumulative Layout Shift) - [ ] TTFB (Time to First Byte) - [ ] FCP (First Contentful Paint) - [ ] INP (Interaction to Next Paint) ### Step 5: Performance Testing - [ ] Test on slow connection (Chrome DevTools → Network → Slow 3G) - [ ] Verify poor performance triggers Sentry warnings - [ ] Check Sentry breadcrumbs include Web Vitals data ## Optional: Google Analytics If using GA4: - [ ] Verify `gtag` function is available - [ ] Check GA4 Real-Time events for Web Vitals - [ ] Verify custom event parameters are logged ## Production Readiness ### Performance Budgets - [ ] Define acceptable thresholds for your app - [ ] Set up Sentry alerts for poor performance: - [ ] LCP > 4000ms - [ ] FID > 300ms - [ ] CLS > 0.25 ### Monitoring Setup - [ ] Create Sentry dashboard for Web Vitals - [ ] Set up email/Slack alerts for poor performance - [ ] Configure metric retention period - [ ] Set up weekly performance review process ### Documentation - [ ] Team knows how to view Web Vitals in Sentry - [ ] Performance thresholds documented - [ ] Escalation process for poor performance defined ## Deployment ### Pre-Deployment - [ ] All tests pass - [ ] No TypeScript errors - [ ] No lint errors - [ ] Code reviewed - [ ] Sentry DSN configured in production environment ### Post-Deployment - [ ] Verify metrics appear in Sentry production project - [ ] Check baseline performance metrics - [ ] Set up automated performance regression tests - [ ] Monitor for 24 hours and verify data collection ## Troubleshooting ### Metrics Not Appearing - [ ] Check `NEXT_PUBLIC_SENTRY_DSN` is set - [ ] Verify Sentry is initialized - [ ] Check browser console for errors - [ ] Confirm `` is rendered ### Test Failures - [ ] Run `npm install` to ensure dependencies - [ ] Check Jest configuration - [ ] Verify mocks are correct - [ ] Clear Jest cache: `npx jest --clearCache` ### TypeScript Errors - [ ] Run `npm install @types/node` - [ ] Check `tsconfig.json` includes `lib/monitoring` - [ ] Verify `web-vitals` types are installed ### Poor Performance Detected If you see poor ratings: - [ ] Review Sentry Performance waterfall - [ ] Check Network tab for slow resources - [ ] Use Lighthouse for detailed recommendations - [ ] Implement suggested optimizations - [ ] Re-test and verify improvements ## Maintenance ### Regular Reviews (Weekly) - [ ] Review Web Vitals trends in Sentry - [ ] Identify pages with poor performance - [ ] Prioritize optimization tasks - [ ] Track improvement over time ### Updates (Monthly) - [ ] Update `web-vitals` package - [ ] Review Google's Web Vitals recommendations - [ ] Adjust thresholds if needed - [ ] Update documentation ## Sign-Off Implementation completed by: _______________ Date: _______________ Verified by: _______________ Date: _______________ ## Notes --- **Need Help?** - API Documentation: `lib/monitoring/README.md` - Integration Guide: `lib/monitoring/INTEGRATION.md` - Implementation Details: `lib/monitoring/IMPLEMENTATION_SUMMARY.md`