Heroku Buildpack for Node.js

This is the official Heroku buildpack for Node.js apps. If you fork this repository, please update this README to explain what your fork does and why it's special.

Documentation

For more information about using Node.js and buildpacks on Heroku, see these Dev Center articles:

• Heroku Node.js Support
• Getting Started with Node.js on Heroku
• 10 Habits of a Happy Node Hacker
• Buildpacks
• Buildpack API

Locking to a buildpack version

In production, you frequently want to lock all of your dependencies - including buildpacks - to a specific version. That way, you can regularly update and test them, upgrading with confidence.

First, find the version you want from the list of buildpack versions. Then, specify that version with buildpacks:set:

heroku buildpacks:set https://github.com/heroku/heroku-buildpack-nodejs#v75 -a my-app

If you have trouble upgrading to the latest version of the buildpack, please open a support ticket at help.heroku.com so we can assist.

Options

Specify a node version

Set engines.node in package.json to the semver range (or specific version) of node you'd like to use. (It's a good idea to make this the same version you use during development)

"engines": {
  "node": "0.11.x"
}

"engines": {
  "node": "0.10.33"
}

Default: the latest stable version.

Specify an npm version

Set engines.npm in package.json to the semver range (or specific version) of npm you'd like to use. (It's a good idea to make this the same version you use during development)

Since 'npm 2' shipped several major bugfixes, you might try:

"engines": {
  "npm": "2.x"
}

"engines": {
  "npm": "^2.1.0"
}

Default: the version of npm bundled with your node install (varies).

Enable or disable node_modules caching

For a 'clean' build without using any cached node modules:

heroku config:set NODE_MODULES_CACHE=false
git commit -am 'rebuild' --allow-empty
git push heroku master
heroku config:unset NODE_MODULES_CACHE

Caching node_modules between builds dramatically speeds up build times. However, npm install doesn't automatically update already-installed modules as long as they fall within acceptable semver ranges, which can lead to outdated modules.

Default: NODE_MODULES_CACHE defaults to true

Enable or disable devDependencies installation

During local development, npm install installs all dependencies and all devDependencies (test frameworks, build tools, etc). This is usually something you want to avoid in production, so npm has a 'production' config that can be set through the environment:

To install dependencies only:

heroku config:set NPM_CONFIG_PRODUCTION=true

To install dependencies and devDependencies:

heroku config:set NPM_CONFIG_PRODUCTION=false

Default: NPM_CONFIG_PRODUCTION defaults to true on Heroku

Configure npm with .npmrc

Sometimes, a project needs custom npm behavior to set up proxies, use a different registry, etc. For such behavior, just include an .npmrc file in the root of your project:

# .npmrc
registry = 'https://custom-registry.com/'

Reasonable defaults for concurrency

This buildpack adds two environment variables: WEB_MEMORY and WEB_CONCURRENCY. You can set either of them, but if unset the buildpack will fill them with reasonable defaults.

• WEB_MEMORY: expected memory use by each node process (in MB, default: 512)
• WEB_CONCURRENCY: recommended number of processes to Cluster based on the current environment

Clustering is not done automatically; concurrency should be part of the app, usually via a library like throng. Apps without any clustering mechanism will remain unaffected by these variables.

This behavior allows your app to automatically take advantage of larger containers. The default settings will cluster 1 process on a 1X dyno, 2 processes on a 2X dyno, and 12 processes on a PX dyno.

For example, when your app starts:

app[web.1]: Detected 1024 MB available memory, 512 MB limit per process (WEB_MEMORY)
app[web.1]: Recommending WEB_CONCURRENCY=2
app[web.1]:
app[web.1]: > example-concurrency@1.0.0 start /app
app[web.1]: > node server.js
app[web.1]: Listening on 51118
app[web.1]: Listening on 51118

Notice that on a 2X dyno, the example concurrency app listens on two processes concurrently.

Chain Node with multiple buildpacks

This buildpack automatically exports node, npm, and any node_modules binaries into the $PATH for easy use in subsequent buildpacks.

Feedback

Having trouble? Dig it? Feature request?

• help.heroku.com
• @hunterloftis
• github issues

Hacking

To make changes to this buildpack, fork it on Github. Push up changes to your fork, then create a new Heroku app to test it, or configure an existing app to use your buildpack:

# Create a new Heroku app that uses your buildpack
heroku create --buildpack <your-github-url>

# Configure an existing Heroku app to use your buildpack
heroku buildpacks:set <your-github-url>

# You can also use a git branch!
heroku buildpacks:set <your-github-url>#your-branch

Testing

The buildpack tests use Docker to simulate Heroku's Cedar and Cedar-14 containers.

To run the test suite:

make test

Or to just test in cedar or cedar-14:

make test-cedar-10
make test-cedar-14

The tests are run via the vendored shunit2 test framework.