5 minute read

Versions and setup

CodeShip uses nvm to manage different Node.js versions. During the Preparing Ubuntu Focal Build Container step of the build, CodeShip attempts to read the Node.js version set in package.json and then installs that version. If the version is not specified in package.json or if your project does not include that file, CodeShip defaults to 16.19.1.

Specifying Version

Even though CodeShip attempts to automatically set the Node.js version for you, it is highly recommended to specify the version to ensure the desired version is used.

In your setup commands you can use nvm commands. For instance:

nvm install NODE_VERSION

Most Node.js versions are pre-installed, but if the version you specify is not already installed, nvm will download it automatically.

The following Node.js versions are preinstalled:

        v12.0.0 *
        v12.1.0 *
        v12.2.0 *
        v12.3.0 *
        v12.3.1 *
        v12.4.0 *
        v12.5.0 *
        v12.6.0 *
        v12.7.0 *
        v12.8.0 *
        v12.8.1 *
        v12.9.0 *
        v12.9.1 *
       v12.10.0 *
       v12.11.0 *
       v12.11.1 *
       v12.12.0 *
       v12.13.0 *
       v12.13.1 *
       v12.14.0 *
       v12.14.1 *
       v12.15.0 *
       v12.16.0 *
       v12.16.1 *
       v12.16.2 *
       v12.16.3 *
       v12.17.0 *
       v12.18.0 *
       v12.18.1 *
       v12.18.2 *
       v12.18.3 *
       v12.18.4 *
       v12.19.0 *
       v12.19.1 *
       v12.20.0 *
       v12.20.1 *
       v12.20.2 *
       v12.21.0 *
       v12.22.0 *
       v12.22.1 *
       v12.22.2 *
       v12.22.3 *
       v12.22.4 *
       v12.22.5 *
       v12.22.6 *
       v12.22.7 *
       v12.22.8 *
       v12.22.9 *
      v12.22.10 *
      v12.22.11 *
      v12.22.12 *
        v13.0.0 *
        v13.0.1 *
        v13.1.0 *
        v13.2.0 *
        v13.3.0 *
        v13.4.0 *
        v13.5.0 *
        v13.6.0 *
        v13.7.0 *
        v13.8.0 *
        v13.9.0 *
       v13.10.0 *
       v13.10.1 *
       v13.11.0 *
       v13.12.0 *
       v13.13.0 *
       v13.14.0 *
        v14.0.0 *
        v14.1.0 *
        v14.2.0 *
        v14.3.0 *
        v14.4.0 *
        v14.5.0 *
        v14.6.0 *
        v14.7.0 *
        v14.8.0 *
        v14.9.0 *
       v14.10.0 *
       v14.10.1 *
       v14.11.0 *
       v14.12.0 *
       v14.13.0 *
       v14.13.1 *
       v14.14.0 *
       v14.15.0 *
       v14.15.1 *
       v14.15.2 *
       v14.15.3 *
       v14.15.4 *
       v14.15.5 *
       v14.16.0 *
       v14.16.1 *
       v14.17.0 *
       v14.17.1 *
       v14.17.2 *
       v14.17.3 *
       v14.17.4 *
       v14.17.5 *
       v14.17.6 *
       v14.18.0 *
       v14.18.1 *
       v14.18.2 *
       v14.18.3 *
       v14.19.0 *
       v14.19.1 *
       v14.19.2 *
       v14.19.3 *
       v14.20.0 *
       v14.20.1 *
       v14.21.0 *
       v14.21.1 *
       v14.21.2 *
       v14.21.3 *
        v15.0.0 *
        v15.0.1 *
        v15.1.0 *
        v15.2.0 *
        v15.2.1 *
        v15.3.0 *
        v15.4.0 *
        v15.5.0 *
        v15.5.1 *
        v15.6.0 *
        v15.7.0 *
        v15.8.0 *
        v15.9.0 *
       v15.10.0 *
       v15.11.0 *
       v15.12.0 *
       v15.13.0 *
       v15.14.0 *
        v16.0.0 *
        v16.1.0 *
        v16.2.0 *
        v16.3.0 *
        v16.4.0 *
        v16.4.1 *
        v16.4.2 *
        v16.5.0 *
        v16.6.0 *
        v16.6.1 *
        v16.6.2 *
        v16.7.0 *
        v16.8.0 *
        v16.9.0 *
        v16.9.1 *
       v16.10.0 *
       v16.11.0 *
       v16.11.1 *
       v16.12.0 *
       v16.13.0 *
       v16.13.1 *
       v16.13.2 *
       v16.14.0 *
       v16.14.1 *
       v16.14.2 *
       v16.15.0 *
       v16.15.1 *
       v16.16.0 *
       v16.17.0 *
       v16.17.1 *
       v16.18.0 *
       v16.18.1 *
       v16.19.0 *
->     v16.19.1 *
        v17.0.0 *
        v17.0.1 *
        v17.1.0 *
        v17.2.0 *
        v17.3.0 *
        v17.3.1 *
        v17.4.0 *
        v17.5.0 *
        v17.6.0 *
        v17.7.0 *
        v17.7.1 *
        v17.7.2 *
        v17.8.0 *
        v17.9.0 *
        v17.9.1 *
        v18.0.0 *
        v18.1.0 *
        v18.2.0 *
        v18.3.0 *
        v18.4.0 *
        v18.5.0 *
        v18.6.0 *
        v18.7.0 *
        v18.8.0 *
        v18.9.0 *
        v18.9.1 *
       v18.10.0 *
       v18.11.0 *
       v18.12.0 *
       v18.12.1 *
       v18.13.0 *
       v18.14.0 *
       v18.14.1 *
        v19.0.0 *
        v19.0.1 *
        v19.1.0 *
        v19.2.0 *
        v19.3.0 *
        v19.4.0 *
        v19.5.0 *
        v19.6.0 *
        v19.6.1 *


You can use npm to install your dependencies. We set the $PATH to include the node_modules/.bin folder so all executables installed through npm can be run.

If you have a npm version specified in your package.json file, it won’t get picked up by nvm automatically. Please include the following snippet in your setup steps to install the specified version.

npm install --global npm@"$(jq -r '.engines.npm' package.json)"

If you simply want to upgrade npm to the latest available version add the following command to your setup steps.

npm install -g npm@latest

npm Private Modules

In order to use private NPM modules, you’ll need to login on your local machine and take a look at your ~/.npmrc file. You’ll find a registry URL as well as an authentication token.

~/.npmrc file example:


Once you have these, configure them as environment variables in your Project Settings > Environment page

+Add the following script to the Setup Commands section of your test configuration.

echo "//${REGISTRY_URL}/:_authToken=${AUTH_TOKEN}" > "${HOME}/.npmrc"

Dependency Cache

CodeShip automatically caches the $REPO_ROOT/node_modules directory between builds to optimize build performance. You can read this article to learn more about the dependency cache and how to clear it. We also configure yarn to write into $HOME/cache/yarn, which is also cached.

Caching Globally Installed Dependencies

If you want to cache packages installed via the -g switch as well, please add the following command to your setup steps.

npm config set cache "${HOME}/cache/npm/"
export PATH="${HOME}/cache/npm/bin/:${PATH}"
export PREFIX="${HOME}/cache/npm/"

Scoped Packages

Scoped packages are only available for versions of npm greater than 2.7.0.

To create a scoped package, you simply use a package name that starts with your scope.

  "name": "@username/project-name"

If you use npm init, you can add your scope as an option to that command.

npm init --scope=username

If you use the same scope all the time, you will probably want to set this option in your ~/.npmrc file.

npm config set scope username


You can also use Yarn to install your dependencies as an alternative to npm. Yarn 1.22.19 is pre-installed on the build VMs and requires your project to use Node.js 4.0 or higher.

If you want to install the latest version of Yarn, there are several ways to do it, including:

curl -o- -L | bash

export PATH="$HOME/.yarn/bin:$PATH"


You can also use Bower for working with dependencies.

To install the latest version add this step to your build:

npm install -g bower

Note that the Bower project recommends migrating to Yarn as an alternative to Bower.


You can install webpack via NPM, as seen below:

npm install webpack

Note that you may need to specify a specific version of Node.js via nvm to use webpack successfully.

Frameworks And Testing

All versions of Node.js run on CodeShip. Additionally, all tools and test frameworks, such as karma, mocha, grunt or any other node-based tool should work without issue. You will need to be sure to install them via npm before using them, however.

Parallel Testing

If you are running parallel test pipelines, you will want separate your tests into groups and call a group specifically in each pipeline. For instance:

Pipeline 1:

mocha tests/test_1.js

Pipeline 2:

mocha tests/test_2.js

Parallelization Modules

In addition to parallelizing your tests explicitly via parallel pipelines, some customers have found using the mocha-parallel-tests npm is a great way to speed up your tests.

Note that we do not officially support or integrate with this module and that it is possible for this to cause resource and build failure issues, as well.

Notes And Known Issues

Due to Node.js version issues, you may find it helpful to test your commands with different versions via an SSH debug session if tests are running differently on CodeShip compared to your local machine.

Running grunt

Do not run npm test to execute grunt tests. When a grunt test fails, it will return a non-zero exit code to npm. npm will ignore this exit code and return with an exit code of zero. We determine the status of your test commands based on the exit code of that command. An exit code of zero will make the command succeed, even if your tests failed.

Instead of npm test run your test commands directly via grunt using the following command.

grunt test


If you want to use io.js simply add the following step to your setup commands.

nvm use iojs-v3

You can then either use the node or the iojs binary to run your applications.

If you want to use a more specific version you need to add the following steps to your setup commands:

nvm install "$(jq -r '.engines.node' package.json)"

Combined with setting the engine to e.g iojs-v1.5.1 this installs and selects the required version.