Upsun User Documentation
Edit page

Manage Node.js versions

Back to home

On this page

Upsun Beta access

Test and provide feedback for our newest offering - Upsun!

You can register for the Beta by clicking here and completing the form.

Sign up for Beta access

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:

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 Anchor to this heading

The n package works for various Unix-like systems, including Windows Subsystem for Linux.

  1. 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"
  }
}

  2. 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.

  1. 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
  1. 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 Anchor to this heading

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:

  1. 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
  1. 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.

  1. 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
  1. 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"

  1. 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"

Is this page helpful?