jkogara / heroku-buildpack-nodejs

The official Heroku buildpack for Node.js apps.

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.

How it Works

Apps are built via one of four paths:

1. A regular npm install (first build; default scenario)
2. Copy existing node_modules from cache, then npm prune, then npm install (subsequent builds)
3. Skip dependencies (if package.json doesn't exist but server.js does)
4. Skip cache, run npm rebuild before npm install (node_modules are checked into source control)

You should only use #3 (omitting package.json) for quick tests or experiments.

You should never use #4 - it's included for backwards-compatibility and will generate warnings. Checking in node_modules is an antipattern. For more information, see the npm docs

For technical details, check out the heavily-commented compile script.

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

Legacy Compatibility

For most Node.js apps this buildpack should work just fine. If, however, you're unable to deploy using this new version of the buildpack, you can get your app working again by locking it to the previous version:

heroku config:set BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-nodejs#v63 -a my-app
git commit -am "empty" --allow-empty
git push heroku master

Then please open a support ticket at help.heroku.com so we can diagnose and get your app running on the default buildpack.

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/'

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 config:set BUILDPACK_URL=<your-github-url>

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

Testing

Anvil is a generic build server for Heroku.

gem install anvil-cli

The heroku-anvil CLI plugin is a wrapper for anvil.

heroku plugins:install https://github.com/ddollar/heroku-anvil

The ddollar/test buildpack runs bin/test on your app/buildpack.

heroku build -b ddollar/test # -b can also point to a local directory

For more info on testing, see Best Practices for Testing Buildpacks on the Heroku discussion forum.