andrei/maternal-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a0e0bbb00201904820428d7252a872d793307caf
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

8.6 KiB
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
  • 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
  • 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

# 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