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

Standard Node 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

You first need to create a read-only token to access the repository. Then, update the package.json to specify the dependency with:

"package-name": "git+https://<token>:x-oauth-basic@<SCM hostname>/<workspace>/<repo>.git"

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

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 grun/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": "4.2.x",
    "npm": "2.14.x"

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

You may want to run custom commands or scripts before or after the installation of dependencies. This is possible thanks to commands named prebuild and postbuild. The first is run before installing dependencies and the latter after. To use them, add the commands you wish to run in the package.json the following way:

  "scripts": {
    "prebuild": "node prebuild.js",
    "build": "grunt build",
    "postbuild": "newrelic deployments"
  • The hook prebuild lets you execute commands before npm/yarn has installed dependencies, so it should not use any of them. It has the following alias: scalingo-prebuild.
  • The hook build is the standard task to bundle applications in most Node.js apps.
  • The hook postbuild triggers tasks unrelated to the build, like notifying some external services or applying migrations. It has the following alias: scalingo-postbuild.

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