Manage Node.js versions

You may need to use a specific version of Node.js that isn’t available in an app container for a different language. For example, a container might have a long-term support version, while you want the latest version.

In such cases, use a version manager to install the specific version you want to use. You could use one of these:

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.

  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:

    .platform.app.yaml
    dependencies:
        nodejs:
            n: "*"

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

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

    .platform.app.yaml
    variables:
        env:
            N_PREFIX: /app/.global
  4. Install the specified version of Node.js in a build hook:

    .platform.app.yaml
    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:

.platform.app.yaml
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:

  1. Define which nvm version to use using an environment variable. Add it to your app configuration:

    .platform.app.yaml
    variables:
        env:
            # Update for your desired NVM version.
            NVM_VERSION: v0.38.0
  2. Define your desired Node.js version using an environment variable. For your base version, set it in your app configuration:

    .platform.app.yaml
    variables:
        env:
            # Update these for your desired NVM and Node versions.
            NVM_VERSION: v0.38.0
            NODE_VERSION: v18.12.0

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

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

    .platform.app.yaml
    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        
  4. Use the cache directory and install based on the variables if not present:

    .platform.app.yaml
    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"        
  5. 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:

variables:
    env:
        # Update these for your desired NVM and Node versions.
        NVM_VERSION: v0.38.0
        NODE_VERSION: v14.17.6

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"