README.md

Node.js Yarn Cloud Native Buildpack

Heroku's official Cloud Native Buildpack for Yarn.

This buildpack relies on and builds on top of the Node.js Engine Cloud Native Buildpack to add yarn functionality to a Node.js app.

What it does

• Installs the yarn CLI (if it's not already installed) and caches it for reuse between builds
• Installs package.json dependencies (including devDependencies) with yarn install. Dependencies are cached between builds to provide fast rebuilds.
• Runs build scripts from package.json, including heroku-prebuild, heroku-build (or build), and heroku-postbuild.
• Sets the default process type as yarn run start if it exists.

Features

Supported:

• Yarn major versions 1, 2, and 3.
• Yarn pnp (Plug 'n Play) mode for yarn 2+.
• Yarn zero-installs for yarn 2+.

Unsupported:

• Optional devDependencies. devDependencies are always installed.
• Pruning devDependencies. devDependencies are always installed.

Reference

Detect

This buildpack's bin/detect will only pass if a yarn.lock exists in the project root. This is done to prevent the buildpack from providing indeterminate and unpredictable dependency trees.

Environment Variables

PATH

$PATH will be modified such that yarn is available.

Zero-installs

Yarn zero-installs are supported for yarn 2+. If the buildpack detects that a populated yarn cache is provided with the source code, this buildpack will not attempt to cache dependencies and prefer the provided cache. Additionally, this buildpack will use the --check-cache and --immutable-cache to ensure the provided cache is pristine. To use zero-installs, make sure the project's .gitignore matches yarn's suggestion.

Plug 'n Play

Yarn plug 'n play is supported for yarn 2+. Ensure nodeLinker: "pnp" is in the project's .yarnrc.yml to use this feature.

Scripts

After dependencies are installed, build scripts will be run in this order: heroku-prebuild, heroku-build (falling back to build if heroku-build does not exist), heroku-postbuild.

Process types

If a start script is detected in package.json, the default process type for the build will be set to yarn start.

Yarn version selection

By default, this buildpack will install the latest yarn version from the 1.22.x line. There are two ways to select a different yarn version:

packageManager

Use the heroku/nodejs-corepack buildpack to install yarn. It will install yarn according to the packageManager key in package.json. For example:

// package.json
{
  "packageManager": "[email protected]"
}

engines.yarn

Alternatively, define engines.yarn using a semver range in package.json. For example:

// package.json
{
  "engines": {
    "yarn": "3.1.x"
  }
}

Usage

To build an app locally into an OCI Image with this buildpack, use the pack command from Cloud Native Buildpacks using both the heroku/nodejs-engine buildpack and this one:

pack build example-app-image --buildpack heroku/nodejs-engine --buildpack heroku/nodejs-yarn --path /some/example-app

Build Plan

Provides

Name	Description
yarn	Allows other buildpacks that require Yarn tooling to depend on this buildpack.
node_modules	Allows other buildpacks to depend on the Node modules provided by this buildpack.
node_build_scripts	Allows other buildpacks to depend on the build script execution behavior provided by this buildpack.

Requires

Name	Description
node	To execute pnpm a Node.js runtime is required. It can be provided by the heroku/nodejs-engine buildpack.
yarn	To install node modules, the Yarn package manager is required. It can be provided by either the heroku/nodejs-corepack buildpack or this one.
node_modules	This is not a strict requirement of the buildpack. Requiring node_modules ensures that this buildpack can be used even when no other buildpack requires node_modules.
node_build_scripts	This is not a strict requirement of the buildpack. Requiring node_build_scripts ensures that this buildpack will perform build script execution even when no other buildpack requires node_build_scripts.

Build Plan Metadata Schemas

node_build_scripts

• enabled (boolean, optional)

Example

[[requires]]
name = "node_build_scripts"

[requires.metadata]
enabled = false # this will prevent build scripts from running

Additional Info

For development, dependencies, contribution, license and other info, please refer to the root README.md.