This article is about Codeship Basic.


You'll need roughly 6 minutes to read this article.

Versions And Setup

We use nvm to manage different node versions. We read the node version you set in your package.json and install the appropriate one. You can use nvm in your setup commands, such as:

nvm install NODE_VERSION

If the version isn’t already pre-installed on the build VMs nvm will download the version from the official repositories and make it available to your build.

Default Version

The default version when we can’t find a setting in your package.json is the latest version of the 0.10 release.

Pre-installed versions

We have the latest versions of the following NodeJS releases pre-installed on our build VMs: 0.8.x, 0.9.x, 0.10.x, 0.11.x, 0.12.x, 4.x, 5.x and 6.x.

Please note that we only install the latest version for each of those releases. You can however install any custom version via the nvm install command mentioned above.


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

npm Private Module Environment Variables

+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 avalaible 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 is pre-installed on the build VMs and requires Node.js 4.0 or higher.


You can install webpack via NPM, as seen below:

npm install webpack

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

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 version issues, you may find it helpful to tests 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

Frameworks And Testing

All versions of node 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.


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