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.
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
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.
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.
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).
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_CACHECaching 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
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=trueTo install dependencies and devDependencies:
heroku config:set NPM_CONFIG_PRODUCTION=falseDefault: NPM_CONFIG_PRODUCTION defaults to true on Heroku
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/'
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.
This buildpack automatically exports node, npm, and any node_modules binaries
into the $PATH for easy use in subsequent buildpacks.
Having trouble? Dig it? Feature request?
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
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.