andrei/maternal-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e07aaa5016d792535e46a9937a8fd0e98ee74621
maternal-app/maternal-web/PACKAGE_UPGRADE_PLAN.md
Andrei fa4be52185 chore(frontend): Upgrade Next.js 14 → 15.5 and React 18 → 19 
- Next.js upgraded from 14.2.0 to 15.5.4
- React upgraded from 18 to 19.2.0
- react-dom upgraded from 18 to 19.2.0

Frontend server working correctly:
- Dev server starts successfully
- Pages compile without errors
- HTTP 200 responses on all routes

Next steps:
- Fix next.config.js warning (swcMinify is deprecated)
- Upgrade MUI packages
- Upgrade testing libraries
2025-10-02 16:00:38 +00:00

284 lines
8.6 KiB
Markdown
Raw Blame History

# 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
Reference in New Issue View Git Blame Copy Permalink