Skip to content

Latest commit

 

History

History
123 lines (81 loc) · 7.13 KB

README.md

File metadata and controls

123 lines (81 loc) · 7.13 KB
Raw

Node.js Yarn Cloud Native Buildpack

Heroku's official Cloud Native Buildpack for Yarn.

CI

Registry

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.

Build Plan

This buildpack requires node (from the heroku/nodejs-engine buildpack). It also provides and requires yarn and node_modules.

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": "yarn@3.1.2"
}

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

Additional Info

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