Heroku Cloud Native Buildpacks: Node.js

This repository is the home of Heroku Cloud Native Buildpacks for Node.js applications. These buildpacks build Node.js application source code into application images with minimal configuration.

Important

This is a collection of Cloud Native Buildpacks, and is a component of the Heroku Cloud Native Buildpacks project, which is in preview. If you are instead looking for the Heroku Classic Buildpack for Node.js (for use on the Heroku platform), you may find it here.

Usage

Note

Before getting started, ensure you have the pack CLI installed. Installation instructions are available here.

To build a Node.js application codebase into a production image:

$ cd ~/workdir/sample-nodejs-app
$ pack build sample-app --builder heroku/builder:24

Then run the image:

docker run --rm -it -e "PORT=8080" -p 8080:8080 sample-app

Application Requirements

The heroku/nodejs buildpack requires a valid package.json to be present to build.

In order to install dependencies, a valid npm, yarn, or pnpm lockfile must be present.

Configuration

Node.js Version

To select a Node.js version, specify it via engines.node in package.json.

For example, to select the latest release of Node.js version 22, modify your package.json like this:

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

Note

This field supports the same semantic versioning syntax as package.json. E.g.; ^1.0, ~1.0, 1.x, etc. See https://semver.npmjs.com/ for more examples.

Note

If no Node.js version is specified, the latest LTS version will be used. We highly suggest specifying a version to prevent surprise changes.

Package Manager Version

To select a package manager version, specify it via:

• engines.yarn, engines.npm, engines.pnpm

  For example, to select npm, modify your package.json like this:

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

  The version declared in the engine fields supports the same semantic versioning syntax as package.json. E.g.; ^1.0, ~1.0, 1.x, etc. See https://semver.npmjs.com/ for more examples.

• packageManager in package.json

  For example, to select pnpm, modify your package.json like this:

  {
    "engines": {
      "packageManager": "[email protected]"
    }
  }
  

  The version declared in the packageManager field must be an exact version for compatibility with local use of Corepack tooling.

Note

If no package manager is specified, the npm version bundled with Node.js will be used. We highly suggest specifying a package manager and version to prevent surprise changes.

Build Script Hooks

The following scripts from package.json will be executed by the configured package manager in the order listed:

• heroku-prebuild
• heroku-build or build (if both are present, only heroku-build will execute)
• heroku-postbuild

If any of the above scripts are not defined in package.json they will be skipped.

Contributing

Issues and pull requests are welcome. See our contributing guidelines if you would like to help.