admin
008f0fd7ab
- Update Docker base images: node:22-alpine → node:24-alpine - Add engines.node >=24.0.0 to package.json files - Create .nvmrc files with 24.15.0 - Update CI workflow to use node-version: 24.15.0 - Fix jest-e2e.json for uuid@13 ES Module compatibility Validation: - Backend unit tests: 340/340 passed - Frontend unit tests: 137/137 passed - Frontend build: successful (39 static pages)
8.0 KiB
Feature Specification: Node.js Upgrade v22.20.0 → v24.15.0
Feature Branch: 103-node-upgrade
Created: 2026-05-05
Status: Draft
Input: User description: "การอัพเกรด node v22.20.0 เป็นv24.15.0"
User Scenarios & Testing (mandatory)
User Story 1 - Backend Node.js Upgrade (Priority: P1)
As a system administrator, I need to upgrade the Node.js runtime for the NAP-DMS backend from v22.20.0 to v24.15.0 to ensure the system runs on a supported LTS version with the latest security patches and performance improvements.
Why this priority: Node.js v22.x maintenance support ends in 2026, and v24.x is the current LTS with extended support through 2027. Running on an unsupported version creates security risks and blocks dependency updates.
Independent Test: Can be fully tested by upgrading Node.js in a staging environment, running the full test suite, and verifying all API endpoints respond correctly with expected performance metrics.
Acceptance Scenarios:
- Given the backend is running Node.js v22.20.0, When the upgrade to v24.15.0 is applied, Then all backend services start successfully without errors
- Given the upgraded backend, When the full test suite runs, Then 100% of tests pass with no new failures compared to pre-upgrade baseline
- Given the upgraded backend, When API endpoints receive requests, Then response times remain within 5% of pre-upgrade performance baseline
User Story 2 - Frontend Node.js Upgrade (Priority: P1)
As a system administrator, I need to upgrade the Node.js runtime for the NAP-DMS frontend build environment from v22.20.0 to v24.15.0 to ensure compatibility with the latest Next.js and build toolchain versions.
Why this priority: The frontend build pipeline requires Node.js v24+ for optimal compatibility with Next.js 15+ and React 19 features. Staying on v22 blocks framework updates.
Independent Test: Can be fully tested by upgrading Node.js in a staging environment, building the frontend application, and verifying all pages render correctly.
Acceptance Scenarios:
- Given the frontend build uses Node.js v22.20.0, When the upgrade to v24.15.0 is applied, Then the production build completes without errors
- Given the upgraded build environment, When the Next.js application builds, Then all TypeScript compilation passes with zero errors
- Given the built application, When pages are served, Then all routes render correctly with no runtime errors
User Story 3 - Dependency Compatibility Validation (Priority: P2)
As a developer, I need to validate that all project dependencies are compatible with Node.js v24.15.0 to prevent runtime errors and security vulnerabilities.
Why this priority: Major Node.js version upgrades can introduce breaking changes in native dependencies and Node-API modules. Validation prevents production issues.
Independent Test: Can be fully tested by running npm audit and dependency compatibility checks after the Node.js upgrade.
Acceptance Scenarios:
- Given the upgraded Node.js environment, When dependency compatibility checks run, Then no critical compatibility warnings are reported
- Given the upgraded environment, When
npm auditexecutes, Then no new high-severity vulnerabilities are introduced by the Node.js upgrade
User Story 4 - Rollback Capability (Priority: P2)
As a DevOps engineer, I need a documented and tested rollback procedure to revert to Node.js v22.20.0 in case the upgrade causes unforeseen production issues.
Why this priority: Production upgrades carry risk. A tested rollback plan ensures business continuity if issues arise post-deployment.
Independent Test: Can be fully tested by performing a rollback in staging and verifying services return to v22.20.0 baseline functionality.
Acceptance Scenarios:
- Given the system is running Node.js v24.15.0, When the rollback procedure is executed, Then the system returns to Node.js v22.20.0 within 15 minutes
- Given the rolled-back system, When services restart, Then all functionality works as it did before the upgrade attempt
Edge Cases
- What happens when native modules (like bcrypt, sharp) fail to compile under Node.js v24?
- How does the system handle package-lock.json or pnpm-lock.yaml incompatibilities?
- What happens when environment variables specific to Node.js v22 are no longer valid in v24?
- How does the build process handle deprecated Node.js APIs that were removed in v24?
- What happens when the Docker base images for Node.js v24 are not yet available?
- How does the system handle memory allocation differences between Node.js v22 and v24?
Requirements (mandatory)
Functional Requirements
- FR-001: System MUST upgrade backend Node.js runtime from v22.20.0 to v24.15.0
- FR-002: System MUST upgrade frontend build environment Node.js from v22.20.0 to v24.15.0
- FR-003: System MUST ensure all existing tests pass on Node.js v24.15.0 without modification
- FR-004: System MUST update Docker base images to Node.js v24.15.0 (node:24.15.0-alpine or equivalent)
- FR-005: System MUST validate all native dependencies compile successfully on Node.js v24.15.0
- FR-006: System MUST update CI/CD pipelines to use Node.js v24.15.0
- FR-007: System MUST document any breaking changes or migration steps required for developers
- FR-008: System MUST provide rollback procedures to revert to Node.js v22.20.0 if needed
Key Entities (include if feature involves data)
- Node.js Runtime: The JavaScript execution environment for backend and frontend build processes (target: v24.15.0 LTS)
- Docker Base Image: Container images specifying Node.js version (e.g.,
node:24.15.0-alpine3.21) - Package Dependencies: npm/pnpm dependencies that may have native bindings requiring Node.js compatibility
- CI/CD Pipeline: GitHub Actions/Gitea workflows that specify Node.js version for builds and tests
- Environment Configuration:
.nvmrc,package.jsonengines field, and documentation specifying Node.js requirements
Success Criteria (mandatory)
Measurable Outcomes
- SC-001: Backend services start successfully on Node.js v24.15.0 with zero startup errors
- SC-002: 100% of existing unit and integration tests pass on Node.js v24.15.0
- SC-003: API response times remain within 5% of pre-upgrade performance baseline
- SC-004: Frontend production build completes without errors or new warnings on Node.js v24.15.0
- SC-005: No new high or critical security vulnerabilities introduced by Node.js v24.15.0 (per
npm audit) - SC-006: All native dependencies (bcrypt, sharp, etc.) compile and function correctly on Node.js v24.15.0
- SC-007: Rollback to Node.js v22.20.0 completes within 15 minutes with full functionality restored
- SC-008: CI/CD pipelines execute successfully using Node.js v24.15.0 without workflow modifications
Assumptions
- Node.js v24.15.0 LTS is available and stable at the time of upgrade
- Docker images for
node:24.15.0-alpineare published and accessible - The current codebase does not use deprecated Node.js APIs removed in v24
- pnpm is compatible with Node.js v24.15.0
- All third-party dependencies have Node.js v24-compatible versions available
Dependencies
- Docker image availability for Node.js v24.15.0
- Gitea/CI runner access to Node.js v24.15.0
- Development team workstations capable of running Node.js v24.15.0
- Test environment availability for pre-production validation
Notes
- Node.js v24 is the current LTS (Long Term Support) version as of 2025
- Node.js v22 enters maintenance mode in late 2025 and End-of-Life in 2026
- Key improvements in v24 include: improved permission model, experimental TypeScript support, and performance optimizations
- The upgrade should be scheduled during a low-usage maintenance window
- Consider running both versions in parallel during the transition period (blue-green deployment)