Node.js

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

Buildpack

Node.js Buildpack

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.

You can specify the version of yarn you want to use by defining it in the package.json file, with the key engines.yarn

Yarn does not handle private modules, if you use them, keep using npm

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 -a <myapp> 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 it’s runtime, failing to find a dependency.

Usually it’s because npm install has been run, 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 ie. npm install -g grunt. 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>

If the module contains a binary like grunt or gulp, they will be installed in the node_modules/.bin directory, keeping them local and trackable. On Scalingo, the node_modules/.bin directory is added to your PATH, so you can directly use them.

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 some dependencies are building binaries during the installation, if your add these binaries to your repository, it may creates incompatibility with Scalingo runtime environment.

The good method to avoid checking in these files is to add the following content in a .gitignore file and commit this file.

node_modules
bower_components
# Any other file created by grun/gulp/webpack builds

Once that’s done git, will ignore these directory when you’re making your commits.

Specifying a NodeJS 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": "myapp",
  "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 scalingo-prebuild and scalingo-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": {
    "scalingo-prebuild": "node prebuild.js",
    "scalingo-postbuild": "grunt build"
  }
}

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

schedule 24 Mar 2017