Manage Node.js versions

Note

You can now use composable image (BETA) to install runtimes and tools in your application container. To find out more, see the dedicated documentation page.

Each Upsun 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 Upsun 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:

Use n
Use nvm

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, or package.json.
Create a .nvmrc file in your app root:

.nvmrc
v16.13.2
Create a .n-node-version or .node-version file in your app root:

.n-node-version or .node-version
16.13.2
Add an engines.node property to your package.json. This property accepts either an exact version or a range:

package.json
{ "engines": { "node": ">=0.10.3 <15" } }
Add it as a dependency:

.upsun/config.yaml

applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'python:3.9'
        dependencies:
            nodejs:
                n: "*"

Adding it as a dependency ensures it’s cached for future builds.

Set the location of the n files using the N_PREFIX environment variable:

.upsun/config.yaml

applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'python:3.9'
        dependencies:
            nodejs:
                n: "*"
        variables:
            env:
                N_PREFIX: /app/.global

Install the specified version of Node.js in a build hook:

.upsun/config.yaml

applications:
    # The app's name, which must be unique within the project.
    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

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:

.upsun/config.yaml

applications:
    # The app's name, which must be unique within the project.
    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:

.upsun/config.yaml

applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'python:3.9'
        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:

.upsun/config.yaml

applications:
    # The app's name, which must be unique within the project.
    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

To get different versions in different environments, set environment-specific variables.

Add a .nvm directory to your cache in your build hook:

.upsun/config.yaml

applications:
    # The app's name, which must be unique within the project.
    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

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:

.upsun/config.yaml

applications:
    # The app's name, which must be unique within the project.
    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: |
                ...
                # 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:

.environment
```
unset 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:

.upsun/config.yaml

applications:
    # The app's name, which must be unique within the project.
    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"

Integrated environments

Supported environments

Manage Node.js versions

Back to home

On this page

Is this page helpful?

Sign up

Note

Use `n`

Use `nvm`

Note

Is this page helpful?

Manage Node.js versions

On this page

Is this page helpful?

Sign up

Note

Use n

Use nvm

Note

Is this page helpful?

Use `n`

Use `nvm`