# 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 `<WebVitalsReporter />` component to layout

Example:
```tsx
import { WebVitalsReporter } from './components/WebVitalsReporter';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <WebVitalsReporter />
        {children}
      </body>
    </html>
  );
}
```

### 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 `<WebVitalsReporter />` 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

<!-- Add any project-specific notes or customizations here -->

---

**Need Help?**
- API Documentation: `lib/monitoring/README.md`
- Integration Guide: `lib/monitoring/INTEGRATION.md`
- Implementation Details: `lib/monitoring/IMPLEMENTATION_SUMMARY.md`
