Manage Node.js versions
Back to home
On this page
Each Platform.sh container image includes a specific language in a specific version. A set of dependencies is also provided based on that language version. This ensures that your application container is as small and efficient as possible.
Therefore, by default, when you use a Platform.sh container image, you use the Node.js version that’s included in that image, if any.
If you want to use a different Node.js version, use a version manager to install it yourself. You can use one of the following version managers:
Both of the recommendations use a .nvmrc
file to specify the desired Node.js version.
You could also specify a different file or use environment variables.
Use n
The n
package works for various Unix-like systems,
including Windows Subsystem for Linux.
-
Add the desired Node.js version to your environment using
.nvmrc
,.n-node-version
,.node-version
, orpackage.json
.Create a
.n-node-version
or.node-version
file in your app root:.n-node-version or .node-version16.13.2
Add an
engines.node
property to yourpackage.json
. This property accepts either an exact version or a range:package.json{ "engines": { "node": ">=0.10.3 <15" } }
-
Add it as a dependency:
dependencies:
nodejs:
n: "*"
Adding it as a dependency ensures it’s cached for future builds.
- Set the location of the
n
files using theN_PREFIX
environment variable:
variables:
env:
N_PREFIX: /app/.global
- Install the specified version of Node.js in a
build
hook:
hooks:
build: |
# Exit the hook on any failure
set -e
# Install the version specified in the .nvmrc file
n auto
# Reset the location hash to recognize the newly installed version
hash -r
Now your hooks should be able to use the specified version of Node.js.
You can verify this by running node -v
.
Your final app configuration should look something like this:
name: app
type: 'python:3.9'
dependencies:
nodejs:
n: "*"
variables:
env:
N_PREFIX: /app/.global
hooks:
build: |
# Exit the hook on any failure
set -e
# Install the version specified in the .nvmrc file
n auto
# Reset the location hash to recognize the newly installed version
hash -r
Use nvm
Node Version Manager (nvm
) is a bash script for managing Node.js versions.
You can use it to:
- Make a specific version available in the build and optionally the runtime container.
- Control the specific versions to be installed with environment variables, meaning you can also have different versions in different environments.
To use nvm
, follow these steps:
- Define which
nvm
version to use using an environment variable. Add it to your app configuration:
variables:
env:
# Update for your desired NVM version.
NVM_VERSION: v0.39.3
- Define your desired Node.js version using an environment variable. For your base version, set it in your app configuration:
variables:
env:
# Update these for your desired NVM and Node versions.
NVM_VERSION: v0.39.3
NODE_VERSION: v18.14.2
To get different versions in different environments, set environment-specific variables.
- Add a
.nvm
directory to your cache in your build hook:
hooks:
build: |
set -e
unset NPM_CONFIG_PREFIX
export NVM_DIR="$PLATFORM_APP_DIR/.nvm"
# Link cache with app
if [ ! -d "$PLATFORM_CACHE_DIR/.nvm" ]; then
mkdir -p $PLATFORM_CACHE_DIR/.nvm
fi
ln -s $PLATFORM_CACHE_DIR/.nvm $NVM_DIR
Note
Instead of using a symlink between your cache and application directories,
you might need to copy the content of $PLATFORM_CACHE_DIR/.nvm
into $PLATFORM_APP_DIR/.nvm
manually.
To do so, run the following command:
rsync -av $PLATFORM_CACHE_DIR/.nvm $PLATFORM_APP_DIR
- Use the cache directory and install based on the variables if not present:
hooks:
build: |
...
# Check for Node.js version and install if not present
if [ ! -d "$PLATFORM_CACHE_DIR/.nvm/versions/node/$NODE_VERSION" ]; then
# Get nvm install script if correct version not present
export NVM_INSTALL_FILE="${PLATFORM_CACHE_DIR}/nvm_${NVM_VERSION}_install.sh"
if [ ! -f "$NVM_INSTALL_FILE" ]; then
wget -nc -O "$NVM_INSTALL_FILE" "https://raw.githubusercontent.com/nvm-sh/nvm/$NVM_VERSION/install.sh"
fi
# Install, automatically using NODE_VERSION
bash $NVM_INSTALL_FILE
fi
# Activate nvm
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
# Use the specified version
nvm use "$NODE_VERSION"
-
Optional: To use the specified Node.js version in the runtime container and not just the build, activate
nvm
via script:.environmentunset NPM_CONFIG_PREFIX export NVM_DIR="$PLATFORM_APP_DIR/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
Your final app configuration should look something like the following:
name: app
type: 'python:3.9'
variables:
env:
# Update these for your desired NVM and Node versions.
NVM_VERSION: v0.39.3
NODE_VERSION: v18.14.2
hooks:
build: |
set -e
unset NPM_CONFIG_PREFIX
export NVM_DIR="$PLATFORM_APP_DIR/.nvm"
# Link cache with app
if [ ! -d "$PLATFORM_CACHE_DIR/.nvm" ]; then
mkdir -p $PLATFORM_CACHE_DIR/.nvm
fi
ln -s $PLATFORM_CACHE_DIR/.nvm $NVM_DIR
# Check for Node.js version and install if not present
if [ ! -d "$PLATFORM_CACHE_DIR/.nvm/versions/node/$NODE_VERSION" ]; then
# Get nvm install script if correct version not present
export NVM_INSTALL_FILE="${PLATFORM_CACHE_DIR}/nvm_${NVM_VERSION}_install.sh"
if [ ! -f "$NVM_INSTALL_FILE" ]; then
wget -nc -O "$NVM_INSTALL_FILE" "https://raw.githubusercontent.com/nvm-sh/nvm/$NVM_VERSION/install.sh"
fi
# Install, automatically using NODE_VERSION
bash $NVM_INSTALL_FILE
fi
# Activate nvm
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
# Use the specified version
nvm use "$NODE_VERSION"