Skip Navigation
Show nav
Heroku Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Dynos (app containers)
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Command Line
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery
    • Continuous Integration
  • Language Support
    • Node.js
    • Ruby
      • Rails Support
      • Working with Bundler
    • Python
      • Background Jobs in Python
      • Working with Django
    • Java
      • Working with Maven
      • Java Database Operations
      • Working with Spring Boot
      • Java Advanced Topics
    • PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku Data For Redis
    • Apache Kafka on Heroku
    • Other Data Stores
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
    • Compliance
  • Heroku Enterprise
    • Private Spaces
      • Infrastructure Networking
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
    • Single Sign-on (SSO)
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Language Support
  • Node.js
  • Heroku Node.js Support

Heroku Node.js Support

English — 日本語に切り替える

Last updated October 31, 2023

Table of Contents

  • Activation
  • Node.js Runtimes
  • Specifying a Node.js Version
  • Specifying an npm Version
  • Specifying a Yarn Version
  • Build Behavior
  • Customizing the Build Process
  • Cache Behavior
  • Runtime Behavior
  • Default Web Process Type
  • Warnings
  • Add-Ons
  • Multi-Buildpack Behavior
  • Going Further

This document describes the general behavior of Heroku as it relates to the recognition and execution of Node.js applications. For a more detailed explanation of how to deploy an application, see Getting Started with Node.json Heroku.

Activation

The Heroku Node.js buildpack is used when the application has apackage.json file in the root directory.

Node.js Runtimes

Node versions adhere to Semver, the semantic versioning convention popularized by GitHub. Semver uses a version scheme in the form MAJOR.MINOR.PATCH.

  • MAJOR denotes incompatible API changes
  • MINOR denotes added functionality in a backwards-compatible manner
  • PATCH denotes backwards-compatible bug fixes

Supported Runtimes

Heroku supports the Current version of Node.js and all Active Long-Term-Support (LTS) versions. Heroku supports new releases within 24 hours of the official release from the Node team. As the Node.js release schedule illustrates, Heroku currently supports Node.js versions 18.x and 20.x.

node release schedule

Other Available Runtimes

Because Heroku is based on a standard Ubuntu Linux stack, you can run most Node versions (>= 0.10.0) on the platform. However, the buildpack’s testing and support revolves around active LTS and Stable releases.

Specifying a Node.js Version

Always specify a Node.js version that matches the runtime that you’re developing and testing with. To find your version locally:

$ node --version
v20.9.0

First, ensure that your application uses the heroku/nodejs buildpack.

$ heroku buildpacks
=== issuetriage Buildpack URLs
1. heroku/nodejs

To specify the version of Node.js to use on Heroku, use the engines section of the package.json. Drop the v to save only the version number.

{
  "name": "example-app",
  "description": "a really cool app",
  "version": "1.0.0",
  "engines": {
    "node": "20.x"
  }
}

If a Node version isn’t specified in the engines section, Node.js 20.x is used automatically.

To get the latest patch updates from Node, we recommend using an x in the patch. You can also specify a minor range such as 20.9 or an exact version, like 20.9.0.

Because Node does regular security releases on all supported major versions, we recommend specifying a major range to get security updates automatically, for example, 20.x.

Specifying an npm Version

Node.js comes bundled with npm, so most of the time specifying a separate npm version isn’t necessary. However, if you intentionally use a different version of npm locally, specify the same version on Heroku.

{
  "name": "example-app",
  "description": "a really cool app",
  "version": "0.0.1",
  "engines": {
    "npm": "10.x"
  }
}

Specifying a Yarn Version

If you have a yarn.lock file at the root of your application along with package.json, Heroku downloads and installs Yarn. Yarn installs your dependencies. Specify the version that you use locally so that Heroku uses the same version.

{
  "name": "example-app",
  "description": "a really cool app",
  "version": "1.0.0",
  "engines": {
    "yarn": "1.x"
  }
}

Build Behavior

Node projects have the Yarn package manager or the NPM package manager.

If a yarn.lock file is detected in the root of the project, Yarn installs dependencies and runs scripts. Otherwise, npm is used. If you have yarn.lock checked into your project, but want to use npm to build on Heroku, add yarn.lock to your .slugignore file.

Package Installation

By default, Heroku installs all dependencies listed in package.json under dependencies and devDependencies.

After running the installation and build steps, Heroku strips out the packages declared under devDependencies before deploying the application.

Heroku uses the lockfiles, either the package-lock.json or yarn.lock, to install the expected dependency tree. Check those files into Git to ensure the same dependency versions across environments. If you use npm, Heroku uses npm ci to set up the build environment.

Using npm install

If you prefer to use npm install instead of npm ci to create the build environment, you can use the USE_NPM_INSTALL environment variable to let the buildpack know. Run:

$ heroku config:set USE_NPM_INSTALL=true

If you use npm install, you want to use your Heroku cache to speed up your build times. If you don’t use npm install, disable the build cache.

$ heroku config:set NODE_MODULES_CACHE=false

Only Installing dependencies

You can direct Heroku to only install dependencies by setting these environment variables.

  • NPM_CONFIG_PRODUCTION=true for npm
  • YARN_PRODUCTION=true for Yarn v1
$ heroku config:set NPM_CONFIG_PRODUCTION=true YARN_PRODUCTION=true

Skip Pruning

If you need access to packages declared under devDependencies in a different buildpack or at runtime, depending on the package manager used, you can set one of these environment variables to skip the pruning step.

  • NPM_CONFIG_PRODUCTION=false for npm
  • YARN_PRODUCTION=false for Yarn v1
  • YARN2_SKIP_PRUNING=true for Yarn v2+
$ heroku config:set NPM_CONFIG_PRODUCTION=false YARN_PRODUCTION=false YARN2_SKIP_PRUNING=true

NODE_ENV isn’t production

By default NODE_ENV is set to production. If NODE_ENV is any other value, the pruning step is skipped.

$ git push heroku main
...
-----> Pruning devDependencies
       Skipping because NODE_ENV is 'test'
...

Check all the created artifacts into Git, along with the other files generated to use Yarn in the .yarn file.

Customizing the Build Process

If your app has a build step that you want to run when you deploy, you can use a build script in package.json.

"scripts": {
  "start": "node index.js",
  "build": "webpack"
}

If package.json has a build script that requires customization for Heroku, define a heroku-postbuild script, which runs instead of the build script.

"scripts": {
  "start": "node index.js",
  "build": "ng build",
  "heroku-postbuild": "ng build --prod" // this will be run on Heroku
}

If a heroku-postbuild script is specified, the build script does not run.

Heroku-Specific Build Steps

While npm install and yarn install have standard preinstall and postinstall scripts, it’s possible that you want to run scripts only before or after other Heroku build steps. For example, to configure npm, git, or ssh before Heroku installs dependencies, or to build production assets after dependencies are installed.

For Heroku-specific actions, use the heroku-prebuild, heroku-postbuild, and heroku-cleanup scripts.

"scripts": {
  "heroku-prebuild": "echo This runs before Heroku installs dependencies.",
  "heroku-postbuild": "echo This runs after Heroku installs dependencies, but before Heroku prunes and caches dependencies.",
  "heroku-cleanup": "echo This runs after Heroku prunes and caches dependencies."
}

Environment Variables

Your app’s environment is available during the build, so you can adjust build behavior based on the values of environment variables. For example:

$ heroku config:set MY_CUSTOM_VALUE=foobar

Build Flags

If your app runs a build step, make sure that it’s used for development and production. If it’s not, use the build flag environment variable to set flags for the build script. For example, your build step is:

"scripts": {
  "build": "ng build"
}

You can set the NODE_BUILD_FLAGS environment variable.

$ heroku config:set NODE_BUILD_FLAGS="--prod"

Setting this variable runs ng build --prod in the build step instead.

Configuring NPM

npm reads configuration from any environment variables beginning with NPM_CONFIG.

You can also control npm’s behavior via a .npmrc file in your project’s root.

When NPM_CONFIG_PRODUCTION is true, npm automatically runs all scripts in a subshell where NODE_ENV is ‘production.’

Private Dependencies

If pulling from a private dependency source, such as NPM Enterprise or Gemfury, the project must configure an alternate registry with access tokens.

Add the private registry URL to .npmrc. In this case, we specify NPM‘s registry even though it’s public, which replaces this scope with the scope used for the private. Then, add the registry URL that points to using the auth token.

echo "@scope:registry=https://registry.npmjs.org" >> .npmrc
echo -e "//registry.npmjs.org/:_authToken=\${NPM_TOKEN}" >> .npmrc

This registry URL is specific to the npm registry, but other private package registries can have similar URLs. Consult with the private registry’s documentation.

The .npmrc looks like:

@scope:registry=https://registry.npmjs.org
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Verify the addition of NPM_TOKEN to the Heroku config so that the build can access the token and install the private package.

heroku config:set NPM_TOKEN=PRIVATE_NPM_TOKEN

Customize Binary Downloads

You can customize where Node and yarn binaries are downloaded by setting environment variables NODE_BINARY_URL and YARN_BINARY_URL to a custom URL. For instance:

$ heroku config:set NODE_BINARY_URL=https://s3.amazonaws.com/your-custom-binary-url/

Cache Behavior

Heroku maintains a build cache that persists between builds. This cache stores caches for npm, yarn, and bower.

You can disable all caching for Node.js apps if you prefer.

$ heroku config:set NODE_MODULES_CACHE=false
$ git commit -am 'disable node_modules cache' --allow-empty
$ git push heroku main

Custom Caching

Heroku stores the node_modules and bower_components directories by default. You can override these defaults by providing a cacheDirectories array in your top-level package.json.

For example, if you build inside client and server sub-directories.

"cacheDirectories": ["client/node_modules", "server/node_modules"]

Or perhaps your app needs a large dictionary of some sort, stored in data/dictionary.txt.

"cacheDirectories": ["data"]

Runtime Behavior

The buildpack puts node, npm, and node_modules/.bin on the PATH so that you can execute with heroku run or use them directly in a Procfile.

$ cat Procfile
web: npm start

The NODE_ENV environment variable is set to ‘production’ by default, but you can set it to any arbitrary string.

$ heroku config:set NODE_ENV=staging

Usually, you want NODE_ENV to be ‘production.’ Several modules, including express, implicitly change their behavior based on NODE_ENV.

Default Web Process Type

First, Heroku looks for a Procfile specifying your process types.

If no Procfile is present in the root directory of your app during the build process, start your web process by running npm start, a script that you can specify in package.json. For example:

"scripts": {
  "start": "node server.js"
}

If you only want to run non-web processes in your app’s formation, explicitly scale web down and the other process types up. For example:

$ heroku scale web=0 worker=1

Warnings

If a build fails, the Node.js buildpack identifies common issues in Node applications and provides warnings with best practice recommendations.

We also maintain a document to help troubleshoot common Node.js issues.

Add-Ons

No add-ons are provisioned by default. If you need a database for your app, add one explicitly.

$ heroku addons:create heroku-postgresql

Multi-Buildpack Behavior

When using the Node.js buildpack with other buildpacks, it automatically exports the node, npm, and node_modules binaries onto the PATH for subsequent buildpacks to consume.

Going Further

The Heroku Node.js buildpack is open source. For a better technical understanding of how the buildpack works, check out the source code at github.com/heroku/heroku-buildpack-nodejs.

Keep reading

  • Node.js

Feedback

Log in to submit feedback.

Using WebSockets on Heroku with Node.js Migrating from Yarn Classic

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing
  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Github
  • LinkedIn
Heroku is acompany
  • heroku.com
  • Terms of Service
  • Privacy (日本語)
  • Cookies
  • Cookie Preferences
  • Your Privacy Choices
  • © 2023 Salesforce.com