# Frontend (maternal-web) Package Upgrade Plan

**Created**: 2025-10-02
**Status**: In Progress

## Current Versions (Before Upgrade)

### Core Framework
- `next`: 14.2.0 → **Target: 15.x (latest stable)**
- `react`: ^18 → **Target: 19.x (latest)**
- `react-dom`: ^18 → **Target: 19.x (latest)**

### UI Framework
- `@mui/material`: ^5.18.0 → **Target: latest 5.x or 6.x**
- `@mui/icons-material`: ^5.18.0 → **Target: match @mui/material**
- `@mui/material-nextjs`: ^7.3.2 → **Target: latest compatible**
- `@emotion/react`: ^11.14.0 → **Target: latest 11.x**
- `@emotion/styled`: ^11.14.1 → **Target: latest 11.x**
- `tailwindcss`: ^3.4.1 → **Target: latest 3.x**

### State Management
- `@reduxjs/toolkit`: ^2.9.0 → **Target: latest 2.x**
- `react-redux`: ^9.2.0 → **Target: latest 9.x**
- `redux-persist`: ^6.0.0 → **Target: latest 6.x**
- `@tanstack/react-query`: ^5.90.2 → **Target: latest 5.x**

### Forms & Validation
- `react-hook-form`: ^7.63.0 → **Target: latest 7.x**
- `@hookform/resolvers`: ^5.2.2 → **Target: latest compatible**
- `zod`: ^3.25.76 → **Target: latest 3.x**

### Testing
- `jest`: ^30.2.0 → **Already latest ✓**
- `jest-environment-jsdom`: ^30.2.0 → **Already latest ✓**
- `@testing-library/react`: ^16.3.0 → **Target: latest 16.x**
- `@testing-library/jest-dom`: ^6.9.0 → **Target: latest 6.x**
- `@testing-library/user-event`: ^14.6.1 → **Target: latest 14.x**
- `@playwright/test`: ^1.55.1 → **Target: latest**
- `@axe-core/react`: ^4.10.2 → **Target: latest 4.x**
- `jest-axe`: ^10.0.0 → **Target: latest 10.x**
- `ts-jest`: ^29.4.4 → **Target: latest 29.x**

### Other Dependencies
- `axios`: ^1.12.2 → **Already latest ✓**
- `socket.io-client`: ^4.8.1 → **Target: latest 4.x**
- `date-fns`: ^4.1.0 → **Target: latest 4.x**
- `framer-motion`: ^11.18.2 → **Target: latest 11.x**
- `recharts`: ^3.2.1 → **Target: latest 3.x**
- `react-markdown`: ^10.1.0 → **Target: latest compatible with React 19**
- `remark-gfm`: ^4.0.1 → **Target: latest 4.x**
- `next-pwa`: ^5.6.0 → **Target: check compatibility with Next.js 15**
- `workbox-webpack-plugin`: ^7.3.0 → **Target: latest 7.x**
- `workbox-window`: ^7.3.0 → **Target: latest 7.x**

## Upgrade Strategy

### Phase 1: Next.js 14 → 15 (CRITICAL - Breaking Changes Expected)
**Priority**: HIGH - This is the most critical upgrade
**Risk**: HIGH - Next.js 15 has significant breaking changes

**Steps**:
1. Review Next.js 15 migration guide
2. Upgrade Next.js: `npm install next@latest`
3. Check for breaking changes in:
   - App Router behavior
   - Image optimization
   - Middleware
   - API routes
   - next.config.js
4. Test dev server
5. Test build process
6. Run all tests
7. Commit: "chore: Upgrade Next.js to v15"

**Potential Breaking Changes**:
- React 19 requirement (must upgrade together)
- Changes to middleware execution
- Image component updates
- Metadata API changes
- Font optimization changes

### Phase 2: React 18 → 19 (HIGH RISK - Breaking Changes)
**Priority**: HIGH - Required for Next.js 15
**Risk**: HIGH - React 19 has breaking changes

**Steps**:
1. Review React 19 migration guide
2. Upgrade React packages: `npm install react@latest react-dom@latest`
3. Check for breaking changes:
   - New JSX Transform
   - Concurrent features
   - Automatic batching
   - useEffect cleanup timing
   - Deprecated APIs
4. Test all components
5. Run all tests
6. Commit: "chore: Upgrade React to v19"

**Potential Breaking Changes**:
- Removal of deprecated APIs
- Changes to hydration behavior
- Stricter concurrent mode
- Changes to useEffect timing

### Phase 3: MUI Material v5 → v6 (if available)
**Priority**: MEDIUM
**Risk**: MEDIUM - MUI v6 may have breaking changes

**Steps**:
1. Check MUI v6 release status and migration guide
2. Upgrade MUI packages:
   ```
   npm install @mui/material@latest @mui/icons-material@latest @mui/material-nextjs@latest
   ```
3. Check for breaking changes:
   - Component API changes
   - Theme structure updates
   - Style engine changes
4. Test all UI components
5. Commit: "chore: Upgrade MUI to v6"

**Note**: If v6 is not stable, upgrade to latest v5.x instead

### Phase 4: Testing Libraries
**Priority**: MEDIUM
**Risk**: LOW

**Steps**:
1. Upgrade Playwright: `npm install --save-dev @playwright/test@latest`
2. Upgrade Testing Library packages:
   ```
   npm install --save-dev @testing-library/react@latest @testing-library/jest-dom@latest @testing-library/user-event@latest
   ```
3. Upgrade accessibility testing:
   ```
   npm install --save-dev @axe-core/react@latest jest-axe@latest
   ```
4. Run test suite
5. Commit: "chore: Upgrade testing libraries"

### Phase 5: State Management & Data Fetching
**Priority**: LOW
**Risk**: LOW

**Steps**:
1. Upgrade Redux packages:
   ```
   npm install @reduxjs/toolkit@latest react-redux@latest redux-persist@latest
   ```
2. Upgrade React Query: `npm install @tanstack/react-query@latest`
3. Test state management
4. Commit: "chore: Upgrade state management libraries"

### Phase 6: Forms & Validation
**Priority**: LOW
**Risk**: LOW

**Steps**:
1. Upgrade form libraries:
   ```
   npm install react-hook-form@latest @hookform/resolvers@latest zod@latest
   ```
2. Test all forms
3. Commit: "chore: Upgrade form and validation libraries"

### Phase 7: Safe Patch Updates
**Priority**: LOW
**Risk**: VERY LOW

**Steps**:
1. Upgrade all other dependencies:
   ```
   npm update
   ```
2. Check for any issues
3. Run full test suite
4. Commit: "chore: Apply safe patch updates"

### Phase 8: PWA & Service Worker
**Priority**: LOW (but check compatibility)
**Risk**: MEDIUM

**Steps**:
1. Check next-pwa compatibility with Next.js 15
2. Upgrade if compatible: `npm install next-pwa@latest`
3. Upgrade Workbox: `npm install workbox-webpack-plugin@latest workbox-window@latest`
4. Test PWA functionality
5. Commit: "chore: Upgrade PWA dependencies"

**Note**: next-pwa may not yet support Next.js 15 - may need to wait or find alternative

## Breaking Change Checklist

### Next.js 15
- [ ] Review [Next.js 15 upgrade guide](https://nextjs.org/docs/app/building-your-application/upgrading)
- [ ] Check middleware changes
- [ ] Verify Image component behavior
- [ ] Test API routes
- [ ] Verify metadata API
- [ ] Check font optimization
- [ ] Test app router behavior

### React 19
- [ ] Review [React 19 release notes](https://react.dev/blog)
- [ ] Check for deprecated API usage
- [ ] Test concurrent features
- [ ] Verify useEffect behavior
- [ ] Test hydration
- [ ] Check for breaking changes in hooks

### MUI v6 (if upgrading)
- [ ] Review MUI v6 migration guide
- [ ] Test all custom theme overrides
- [ ] Verify component variants
- [ ] Check style engine changes
- [ ] Test responsive behavior

## Testing Checklist (After Each Phase)

- [ ] Dev server starts without errors: `npm run dev`
- [ ] Production build succeeds: `npm run build`
- [ ] Unit tests pass: `npm test`
- [ ] E2E tests pass: `npm run test:e2e`
- [ ] Accessibility tests pass (jest-axe)
- [ ] Manual testing of critical paths:
  - [ ] User authentication
  - [ ] Activity tracking (feeding, sleep, diaper)
  - [ ] Voice input
  - [ ] Analytics dashboard
  - [ ] Family sync
  - [ ] Responsive design
  - [ ] PWA functionality

## Rollback Plan

If any phase fails:
1. `git reset --hard HEAD~1` (undo last commit)
2. Review error messages
3. Check compatibility issues
4. Consider staying on current version if critical issues

## Commands Reference

```bash
# Development
npm run dev              # Start dev server (port 3030)
npm run build            # Production build
npm run start            # Start production server
npm run lint             # Run ESLint

# Testing
npm test                 # Run Jest unit tests
npm run test:watch       # Run Jest in watch mode
npm run test:coverage    # Generate coverage report
npm run test:e2e         # Run Playwright E2E tests
npm run test:e2e:ui      # Run Playwright with UI
npm run test:e2e:headed  # Run Playwright in headed mode

# Upgrade commands
npm outdated             # Check for outdated packages
npm update               # Update to latest within semver range
npm install <pkg>@latest # Install specific package's latest version
```

## Post-Upgrade Verification

After completing all phases:
1. Full regression testing
2. Performance benchmarking
3. Bundle size analysis
4. Lighthouse audit
5. Accessibility audit
6. Cross-browser testing
7. Mobile device testing
8. PWA functionality verification

## Notes

- Using `--legacy-peer-deps` flag if peer dependency conflicts arise
- Document any breaking changes encountered
- Update this plan as you progress through phases
- Commit after each successful phase
- All upgrades tested on dev server before committing