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)
137 lines
8.0 KiB
Markdown
137 lines
8.0 KiB
Markdown
# 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**:
|
|
|
|
1. **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
|
|
2. **Given** the upgraded backend, **When** the full test suite runs, **Then** 100% of tests pass with no new failures compared to pre-upgrade baseline
|
|
3. **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**:
|
|
|
|
1. **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
|
|
2. **Given** the upgraded build environment, **When** the Next.js application builds, **Then** all TypeScript compilation passes with zero errors
|
|
3. **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**:
|
|
|
|
1. **Given** the upgraded Node.js environment, **When** dependency compatibility checks run, **Then** no critical compatibility warnings are reported
|
|
2. **Given** the upgraded environment, **When** `npm audit` executes, **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**:
|
|
|
|
1. **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
|
|
2. **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.json` engines 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-alpine` are 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)
|