Critical: Dependency Upgrades - Node.js EOL & Major Framework Updates

[IanMayo]

Summary

Critical dependency upgrades required, particularly Node.js 18 (EOL) which no longer receives security patches. Additional major version upgrades needed for Vite, react-admin, and Material-UI.

Adoption of Node 22 (LTS) means security patches will be available for this important component until 2027.

Critical Risk

Node.js 18 has reached End of Life and receives zero security updates. This is an immediate production security risk.

Current Test Coverage Gap

Major concern: This project has minimal unit and e2e test coverage:

• Jest tests exist but limited coverage (src/providers/dataProvider/tests/)
• Playwright e2e tests configured but minimal test scenarios
• Large manual testing burden for regression validation
• High risk of breaking changes going undetected during upgrades

Proposed Cost-Effective Approach

Phase 0: Test Improvement Prerequisite

Complete issue #1149 first - This refactoring of business logic into testable modules will improve the quality and effectiveness of tests implemented in Phase 1.

Phase 1: Test Infrastructure (Before Upgrades)

Rationale: Establish comprehensive test coverage FIRST to catch regressions during upgrades. With thorough e2e coverage, dependency upgrades become straightforward validation exercises.

1. Expand Unit Test Coverage

   • Data provider lifecycle callbacks (critical business logic)
   • Authentication/authorization flows
   • Form validation schemas
   • Resource-specific CRUD operations
   • Audit logging functions
   • Target: 70%+ coverage of critical paths

2. Expand E2E Test Coverage

   • User authentication flows (login, logout, session timeout)
   • Item creation/editing workflows
   • Batch management operations
   • Dispatch workflows
   • Destruction workflows
   • Vault location tracking
   • Permission-based access control scenarios
   • Target: All critical user journeys covered

3. Establish Testing Baseline

   • Run full test suite on current dependency versions
   • Document all passing tests as regression baseline
   • Fix any existing test failures

Estimated effort: 3 days

Phase 2: Dependency Upgrades (With Test Safety Net)

Perform upgrades in logical sequence with test validation at each step:

Step 1: Node.js & TypeScript (Day 1-2)

• Upgrade Node.js 18.x → 22.12+ LTS (required for Vite 7, supported until April 2027)
  • Note: Vite 7 requires Node.js 20.19+ or 22.12+
• Upgrade TypeScript 5.0.2 (current) → 5.9.x (latest stable)
  • Currently using wildcard "*" which installed 5.0.2
  • Pin to "^5.9.0" for reproducible builds
  • Key improvements: Inferred type predicates, better array filtering, regex validation, Set methods, 33% smaller package
  • Breaking changes: Minimal - deprecated options from 5.0 removed, stricter type checking in edge cases
  • Review: https://github.com/microsoft/TypeScript/wiki/Breaking-Changes
• Update .nvmrc to specify Node 22.12+
• Update CI/CD pipeline Node version
• Run full test suite
• Manual smoke testing of critical paths

Step 2: Vite 4.2 → 7 (Day 3)

Note: Minimal Vite-specific code (22-line config, 3 plugins). Plugin compatibility check then upgrade.

• Check plugin compatibility:
  • @vitejs/plugin-react - official, auto-updates
  • vite-plugin-babel-macros - verify Vite 7 support
  • vite-plugin-environment - verify Vite 7 support
• Review migration guides:
  • Vite 5: Rollup 4, import attributes, SSR changes
  • Vite 6: Environment API, Module Runner, modern Sass
  • Vite 7: Node 22.12+, baseline browsers, Sass legacy removed
• Upgrade Vite 4.2.0 → 5.x → 6.x → 7.x
• Address breaking changes:
  • Update import assertions → attributes if used
  • Verify modern Sass API (legacy removed in v7)
  • Default browser target now 'baseline-widely-available' (Chrome 107+, Safari 16+)
• Optional: Test Rolldown bundler (rolldown-vite package)
  • 16× faster builds, 100× memory reduction for large projects
• Test dev server, build process, preview
• Run full test suite

Step 3: React 18.2 → 19 (Day 4-5)

• Upgrade React 18.2.0 → 18.3.1 (zero breaking changes, shows deprecation warnings)
• Upgrade react-dom to match
• Check console for deprecation warnings, document issues
• Run full test suite
• Review React 19 upgrade guide: https://react.dev/blog/2024/04/25/react-19-upgrade-guide
• Upgrade React 18.3.1 → 19.x
• Address breaking changes:
  • Remove PropTypes (TypeScript already provides types)
  • Remove defaultProps from function components (use ES6 default params)
  • Update ref usage (ref now regular prop, forwardRef deprecated)
  • Remove legacy Context usage if any
• Run react-codemod tools: https://github.com/reactjs/react-codemod
• Test in React Strict Mode
• Run full test suite

Step 4: Material-UI 5.11 → 7 (Day 6)

Note: With comprehensive e2e coverage, MUI upgrades are primarily validation exercises.

• Review migration guides:
  • MUI v6: Minimal changes, Pigment CSS opt-in
  • MUI v7: Grid→GridLegacy, deep imports, slots
• Upgrade @mui/* packages: 5.11.x → 6.x → 7.x
  • @mui/material, @mui/icons-material, @mui/styles, @mui/system, @mui/x-date-pickers
• Update @emotion/* dependencies if needed
• Run MUI codemods for both versions
• Address v7 breaking changes:
  • Replace Grid with GridLegacy where needed (Grid2 is now Grid)
  • Fix deep imports (top-level only due to Node.js exports field)
  • Update slots/slotProps usage
• Run full test suite (e2e coverage validates UI components)
• Visual regression check

Step 5: react-admin 4.13 → 5.12 (Day 7)

Note: Few relevant breaking changes, thorough e2e coverage validates admin functionality.

• Review upgrade guide: https://marmelab.com/react-admin/Upgrade.html
• Upgrade react-admin 4.13.1 → 5.12+
• Address breaking changes:
  • Remove <Admin menu> prop (deprecated since 4.0)
  • Update custom layouts (only children prop injected)
  • Update <DatagridBody> to use RecordContext
  • Update bulk action buttons to use context hooks
• Run full test suite (validates all CRUD operations, auth flows)

Step 6: Backend Compatibility & Testing (Day 8-9)

• Test soul-cli compatibility with upgraded stack
• Test custom extensions in _extensions/ and _devExtensions/
• Verify database interactions
• Test API endpoints
• Run complete test suite (unit + e2e)
• Performance testing (build time, bundle size, runtime)
• Security audit: npm audit or yarn audit
• Cross-browser testing
• User acceptance testing

Step 7: Deployment Preparation (Day 10)

• Update documentation (README, CLAUDE.md)
• Update CI/CD pipeline configurations
• Update Docker/deployment configs for Node 22.12+
• Create rollback plan
• Schedule deployment window
• Notify team of changes

Estimated upgrade effort: 10 days

Phase 3: Post-Upgrade

• Monitor production for errors
• Track performance metrics (especially build times if using Rolldown)
• Address any issues discovered
• Document lessons learned
• Update dependency management policies

Phase 4: Feature Development (Enabled by Test Suite)

With comprehensive test coverage and modern dependencies in place, implement features efficiently with automated regression detection.

Quick Wins (1.5 days total)

• end-point renaming #1145 - Rename 3 endpoints in _devExtensions - 0.5 days
  • updateBefore → clearPasswordExpiry
  • insertPassword → updatePassword
  • editPassword → adminResetPassword
• Store client-side role-permissions in one place. #1118 - Centralize client-side role permissions - 0.5 days
  • Create clientPermissions file with const values
  • Refactor scattered checks

Feature Enhancements (7.5 days total)

• Modify dispatch form to show which documents were sent #844 - Show sent items in completed dispatches - 0.5 days
  • Query audit log for SENT events by dispatch ID
  • Display items from audit trail
• Move audit logging to backend #1144 - Move audit logging to backend - 2 days
  • Create audit middleware for soul-cli
  • Capture all REST API write operations
  • Parallel run validation, frontend cleanup
• Allow anonymous access to welcome page #1129 - Allow anonymous access - 3 days
  • Allow anonymous/guest access without authentication
  • Implement read-only permissions for unauthenticated users
  • Authorization checks for anonymous sessions
  • Note: Full network auth integration deferred; anonymous access enables wider access quickly
• Future Feature - Users able to submit requests #172 - User request submission feature - 2 days
  • New UserRequest resource with workflow
  • Popup form, status tracking, allocation

Phase 4 total: 9 days

Key benefit: Test suite provides automated regression detection, enabling confident implementation of features that would be too risky without comprehensive testing.

Total Estimated Effort

Complete project timeline:

• Phase 0 (prerequisite): Completed separately (Refactor larger methods, to allow testing #1149)
• Phase 1 (tests): 3 days
• Phase 2 (upgrades): 10 days
• Phase 3 (monitoring): Ongoing
• Phase 4 (features): 7.5 days

Total: 20.5 days for tests + upgrades + all features

Long-term value: Test infrastructure + modern dependencies enable safer, faster development and reduce ongoing maintenance burden.

Dependencies to Upgrade

Critical

• Node.js: 18.x → 22.12+ LTS ⚠️ EOL - No security patches

Major Version Upgrades

• Vite: 4.2.0 → 7.x (minimal config impact)
  • Optional Rolldown: 16× faster builds, 100× less memory
• React: 18.2.0 → 19.x (via 18.3.1)
• @mui/material: 5.11.x → 7.x (via 6.x)
• react-admin: 4.13.1 → 5.12+

Minor Updates

• TypeScript: 5.0.2 → 5.9.x (currently wildcard "*")

TypeScript 5.0.2 → 5.9 Key Changes

5.1-5.2: Using declarations, decorator metadata, array copy methods, 50% faster JSDoc parsing
5.3-5.4: Import attributes, NoInfer utility, better closure narrowing
5.5: Array filtering type narrowing, inferred type predicates, regex validation, new Set methods, 33% smaller package
5.6-5.7: Better truthy/falsy detection, ES2024 target support
5.8-5.9: Erasable syntax flag, granular return checks

Breaking: Minimal - mostly stricter type checking and removed deprecated 5.0 options

Vite 4.2 → 7 Key Changes

Vite 5: Rollup 4, import attributes, SSR improvements
Vite 6: Environment API, Module Runner, modern Sass default
Vite 7: Node 20.19+/22.12+ required, baseline-widely-available browser targets, Sass legacy removed, optional Rolldown (16× faster builds)

References

TypeScript

• TypeScript 5.9 Release Notes
• TypeScript Breaking Changes
• TypeScript Blog

Build Tools

• Vite 5 Migration Guide
• Vite 6 Migration Guide
• Vite 7 Migration Guide
• Vite 7 Announcement

React

• React 19 Upgrade Guide
• React 19 Release
• react-codemod Tools
• TypeScript React Codemods

Material-UI

• MUI v6 Upgrade Guide
• MUI v7 Upgrade Guide
• MUI v7 Release Announcement

React-Admin

• react-admin v5 Upgrade Guide
• react-admin Releases

Node.js

• Node.js 22 LTS Announcement
• Node.js EOL Dates

Related Issues

Prerequisites:

• Refactor larger methods, to allow testing #1149 (complete before Phase 1)

Phase 4 Features:

• end-point renaming #1145 (quick - endpoint renaming)
• Remove concept of _users.is_superuser #1143 (quick - remove is_superuser)
• Store client-side role-permissions in one place. #1118 (quick - centralize permissions)
• Modify dispatch form to show which documents were sent #844 (feature - dispatch form improvements)
• Move audit logging to backend #1144 (feature - backend audit logging)
• Open application for non BAS staff #1147 (feature - anonymous access for non-BAS staff)
• Future Feature - Users able to submit requests #172 (feature - user requests)