Node.js Upgrade Guide
Log in to add to favouritesPage last updated 29 October 2026
Keeping your Contensis React Starter project's Node.js version up to date helps maintain security, performance, and compatibility with modern development tools and dependencies.
When upgrading Node.js in your project, it's important to review the relevant configuration files to ensure a consistent version is used across development, build, and deployment environments.
Before You Begin
Before upgrading, refer to the official Node.js release schedule to identify the latest recommended Long-Term Support (LTS) version.
We recommend using an actively supported LTS version of Node.js to ensure ongoing security updates, stability, and compatibility. Any references to outdated or unsupported versions should be updated accordingly.
Recommended for Active Development Teams
For projects with multiple developers or frequent deployments, we recommend pinning Node.js to a specific version.
This ensures consistent development environments, predictable builds, and easier troubleshooting. It also gives teams greater control over upgrades, allowing new versions to be tested before adoption.
Pinned versions should be reviewed and updated regularly to benefit from the latest security fixes and improvements.
1. Update Docker Configuration Files
Review the following Dockerfiles and update any references to older Node.js versions.
Files to check:
/docker/ci-build.DockerFile/docker/nodebuilder.DockerFile/docker/storybook-builder.DockerFile
Examples of references that may need updating:
FROM node:20
FROM node:20-alpine
FROM node:20 AS builder
FROM node:20-alpine AS builder
Update these references to use your chosen supported LTS version, retaining the appropriate image variant (e.g. Alpine) where applicable.
For example:
FROM node:22
FROM node:22-alpine
FROM node:22 AS builder
FROM node:22-alpine AS builder
Ensure that all relevant Dockerfiles reference the same Node.js version to maintain consistency across build environments.
2. Review package.json
File: package.json
If the project already defines a Node.js version requirement using the engines property, update it to reflect the minimum supported version.
Before:
"engines": {
"node": ">=20"
}
After:
"engines": {
"node": ">=22"
}
Note: Only update the engines property if it already exists. There is no requirement to introduce it as part of this upgrade.
The version specified should align with the Node.js version selected for the project.
3. Update Webpack Configuration
File: webpack.config.prod.js Configuration: SERVER_PROD_CONFIG
Review the esbuild target configuration and ensure it matches the Node.js version being used by the project.
For example, if upgrading to Node.js 22, the esbuild target should be set to:
target: 'node22'
This ensures that the server-side build output is compatible with the project's Node.js runtime.
4. Configure Node Version Management (Recommended)
File: .nvmrc
We recommend adding or updating an .nvmrc file in the project's root directory.
This file specifies the Node.js version required by the project, allowing developers using Node Version Manager (NVM) to easily switch between projects and maintain a consistent development environment.
For example, if the project uses Node.js 22, the .nvmrc file could contain:
22
Developers can then run the following command to switch to the configured version:
nvm use
5. Verify the Upgrade
Once the configuration changes have been made, we recommend completing the following checks:
- Review configuration files: Confirm that all relevant files reference the intended Node.js version.
- Install dependencies: Install project dependencies using the updated Node.js version and check for compatibility issues.
- Run the build: Verify that the project builds successfully with the updated configuration.
- Run automated tests: Execute the available tests to confirm the application continues to function as expected.
- Validate Docker builds: Confirm that Docker images build successfully using the updated Node.js version.
- Check deployment compatibility: Ensure the Node.js version is compatible with the target hosting and deployment environments.
If compatibility issues arise, review the relevant dependency requirements and build configurations before proceeding with deployment.
Summary
Keeping Node.js up to date is an important part of maintaining a secure, stable, and reliable application.
By reviewing the relevant configuration files, selecting a supported LTS release, and validating the upgrade, you can help ensure consistency across your development and deployment environments.
For teams actively maintaining their projects, pinning Node.js versions and adopting a controlled upgrade process can further reduce compatibility issues and improve build reliability.