Node.js is supported by Scalingo, furthermore, custom support has been added to manage the Meteor framework.

Standard Node.js Applications

Node.js App Detection

The file package.json should be present at the root of the project.

Dependencies Installation

The dependencies of your project are installed either with the npm package manager or the Yarn package manager.

If a yarn.lock file is present at the root of your project, yarn will be used to install the dependencies and run scripts, otherwise npm will build the dependencies during the deployment.

Private Dependency

NPM Private Modules

First you need to create a read-only token with the NPM account you want to authenticate:

npm token create --read-only

Then set this token as environment variable (replace the 0-value by the token obtained in the previous command):

scalingo env-set NPM_TOKEN=00000000-0000-0000-0000-00000000

Add the following NPM configuration file .npmrc to the root directory of your project:


Add this file and commit it in your Git repository, the environment variable will be automatically used during the build.

Private Modules from SCM (GitHub/GitLab/etc.)

Your private module should be fetched from the SCM service through SSH. You can specify it this way:

"package-name": "git+ssh://git@<SCMhostname>/<workspace>/<repo>.git#master"

To authenticate to the SCM service, you need to use our SSH Private Key Buildpack, this buildpack will let you setup a private SSH key securely in the build environment.

Install devDependencies

By default, dependencies present in the devDependencies field are not installed since they should not be needed for production. If you want to install them, you’ll need to set the NPM_CONFIG_PRODUCTION environment variable to false via our web interface or by using our CLI:

$ scalingo --app my-app env-set NPM_CONFIG_PRODUCTION=false

After setting the NPM_CONFIG_PRODUCTION environment variable, you have to redeploy your code.

Ensure you’re Tracking all your Dependencies

It is important to ensure you are tracking all the dependencies of your project in the package.json file. Otherwise your app may build but will potentially crash during its runtime, failing to find a dependency.

A common mistake is to run npm install without the --save flag. In this case the dependency is installed in the node_modules directory, but nothing is tracked in the package.json file.

You should also avoid to install global packages (i.e. using the -g flag). In this case packages are installed at the system level and are not tracked for your project.

In a nutshell: you should always use the following command when adding a dependency:

npm install --save <module>

Do not Track Modules with Git

When working locally on your code, after running npm install, a directory node_modules containing the dependencies of your application is created. You should not check this directory in your Git repository. If the dependency is listed in your package.json file, it will automatically be installed during the deployment of your application.

Adding these files to Git will create confusion and unnecessary noise in your code history and we consider it’s a good practice to keep it clean, only add the useful code (the code of your project). Moreover there is an issue with dependencies which build binaries during their installation. If your add these binaries to your repository, it may create incompatibility with Scalingo runtime environment.

The good method to avoid checking in these files is to add the following content in a .gitignore file at the root of your project and commit this file:

# Any other file created by grunt/gulp/webpack builds

Once done, Git will ignore these directories when making commits.

Specifying a Node.js Version

In your engines section of your package.json file, you can specify a version of Node.js to use. If no version is defined, we’ll install the latest stable version. It’s exactly the same with npm if you want to use a specific version of it.

  "name": "my-app",
  "engines": {
    "node": "10",
    "npm": "3"

Node.js App Startup

What we use in order of priority

  1. Procfile at the root of your project
  2. The field .scripts.start defined in your package.json

Example of package.json:

  "scripts": {
    "start": "node server.js"

Node.js Build Hooks

If your application has a build step that you would like to run when you deploy, you can use the build step defined in the package.json:

  "scripts": {
    "start": "node server.js",
    "build": "grunt build"

If the package.json has a build script which needs to be customized for Scalingo, you should define ascalingo-postbuild step:

  "scripts": {
    "build": "grunt build",
    "scalingo-postbuild": "grunt build --prod",
    "start": "node server.js"

You may also want to run a custom command before the installation of dependencies. This is possible thanks to commands named scalingo-prebuild:

  "scripts": {
    "scalingo-prebuild": "node prebuild.js",
    "start": "node server.js"

Custom Cache Folder

By default, Scalingo stores the directories bower_components and node_modules at the root of the project in the deployment cache. But you might need to add different folders to this cache. You can override these defaults by specifying the cacheDirectories (or cache_directories) key at the root of your package.json file.

For example, if your application has a client and a server in the same repository, you can specify these folders to store them in the deployment cache with:

"cacheDirectories": ["client/node_modules", "server/node_modules"]

Meteor Application

If a .meteor file is detected at the root of your project, your app will be considered as a Meteor application.

See the Meteor applications documentation

Framework Requiring to Serve Static Files

Some front-end JavaScript frameworks (such as React Native, Ember.js, Ionic, Next.js, GatsbyJS) build static files and need a minimal web server to serve them. In order to do so, first update your package.json to at least specify the following scripts:

  "scripts": {
    "build": "<build script>",
    "start": "node server.js"

The build script depends on the framework you use:

  • Ember.js: ember build --environment=production
  • GatsbyJS: gatsby build
  • Ionic: ionic-app-scripts build
  • Next.js: next build

The server.js file is a minimal web server such as the one presented here to serve the file generated during the build phase.


More information at

mode_edit Suggest edits