Last updated December 04, 2024

Heroku supports Node.js applications, including ones built with popular frameworks. This document contains version support info.

For a more detailed explanation of how to deploy an application, see Getting Started on Heroku with Node.js or Getting Started on Heroku Fir with Node.js. For general behavior info of Heroku recognizes and executes Node.js applications, see Node.js Behavior in Heroku.

Node.js Runtime

Supported Node.js Versions

For apps using classic buildpacks or Cloud Native Buildpacks, our Node.js version support follows the Node.js support policy. This support includes the following versions according to the Node.js release schedule:

New versions of supported releases are typically available for use on Heroku within 24-48 hours of the official release from the Node.js team. While older versions of Node.js are always available to install on the platform, only use them to incrementally upgrade an application to a supported version.

We recommend:

• Using only Active LTS or Maintenance LTS releases in production
• Always running the latest patch release of supported Node.js versions
• Upgrading before a Node.js release is End-of-life (EOL)

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 run node --version.

To specify the version of Node.js to use on Heroku, use the engines section of package.json.

{
  "name": "example-app",
  "engines": {
    "node": "22.x"
  }
}

If a Node version isn’t specified in the engines section, Node.js 22.x is used automatically. You can also specify a minor range such as 22.11 or an exact version, like 22.11.0.

Specifying a Package Manager

You can build Node.js applications using npm, pnpm, and Yarn. Directions for how to configure each package manager is found below.

Using npm

If you have a package-lock.json file at the root of your application along with package.json, Heroku downloads and installs npm, which is used to install dependencies and build your application.

Node.js comes bundled with npm, so most of the time specifying an npm version isn’t necessary but is recommended. If you intentionally use a different version of npm locally, specify the same version on Heroku.

npm Version Policy

The release-line version of npm bundled with the supported Node.js versions can be used for building Heroku applications. Older versions of npm may continue to work but this is not guaranteed. Using the latest version of npm is recommended.

Specifying an npm Version

To specify the npm version for your application builds, use the engines.npm field in package.json:

{
  "name": "example-app",
  "engines": {
    "npm": "10.x"
  }
}

Using pnpm

If you have a pnpm-lock.yaml file at the root of your application along with package.json, Heroku downloads and installs pnpm which will be used to install dependencies and build your application. The version of pnpm must also be specified.

pnpm Version Policy

Any pnpm version that runs on the supported Node.js versions can be used for building Heroku applications. Older versions of pnpm may continue to work but this is not guaranteed. Using the latest version of pnpm is recommended.

Specifying a pnpm Version

To specify the pnpm version for your application builds, , use one of the following methods:

• Use the packageManager field in package.json

  {
    "name": "example-app",
    "packageManager": "pnpm@9.0.5"
  }
  

This method uses Corepack which is preferred for pnpm tooling. The version declared in package.json must be exact but it can be configured from a version range with Corepack’s use command (e.g.; corepack use pnpm@9.x).

• Use the engines.pnpm field in package.json

  {
    "name": "example-app",
    "engines": {
      "pnpm": "9.0.5"
    }
  }
  

This method allows for version ranges like 9.0 or 9.x to be used. Ranges can be useful for keeping up to date with new releases but are not as safe as exact versions when it comes to reliable builds.

Using Yarn

If you have a yarn.lock file at the root of your application along with package.json, Heroku downloads and installs Yarn which will be used to install your dependencies and build your application. The version of Yarn should also be specified but, if not, version 1.22.x will be installed.

Yarn Version Policy

Any Yarn version that runs on the supported Node.js versions can be used for building Heroku applications. Older versions of Yarn may continue to work but this is not guaranteed. Using the latest version of Yarn is recommended.

Specifying a Yarn Version

To specify the Yarn version for your application builds, use one of the following methods:

• Use the packageManager field in package.json

  {
    "name": "example-app",
    "packageManager": "yarn@4.1.1"
  }
  

This method uses Corepack which is preferred for Yarn tooling. The version declared in package.json must be exact but it can be configured from a version range with Corepack’s use command (e.g.; corepack use yarn@4.x).

• Use the engines.yarn field in package.json

  {
    "name": "example-app",
    "engines": {
      "yarn": "4.1.1"
    }
  }
  

This method allows for version ranges like 4.1 or 4.x to be used. Ranges can be useful for keeping up to date with new releases but are not as safe as exact versions when it comes to reliable builds.

Behavior

For details about how Heroku recognizes and executes Node.js applications, see Node.js Behavior in Heroku.

Additional Reading

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

• Node.js Behavior in Heroku
• Node.js Classic Buildpack Builds
• Node.js Cloud Native Buildpack Builds