The Node.js Paketo Buildpack supports several popular configurations for Node.js apps.
To build a sample app locally with this CNB using the pack
CLI, run
git clone https://github.com/paketo-buildpacks/samples cd samples/nodejs/npm pack build my-app --buildpack gcr.io/paketo-buildpacks/nodejs \ --builder paketobuildpacks/builder:base
Copied!
See samples for how to run the app.
NOTE: Though the example above uses the Paketo Base builder, this buildpack is also compatible with the Paketo Full builder. The Paketo Full builder is required if your app utilizes common C libraries.
The Node.js Paketo Buildpack supports several versions of Node.js. For more details on the specific versions supported in a given buildpack version, see the release notes.
The Node Engine CNB (Cloud Native Buildpack) allows you to specify a version of Node.js to use during
deployment. This version can be specified in a number of ways, including
through the BP_NODE_VERSION
environment variable, a package.json
, .nvmrc
or .node-version
files. When specifying a
version of the Node.js engine, you must choose a version that is available
within the buildpack. The supported versions can be found here.
The buildpack prioritizes the versions specified in
each possible configuration location with the following precedence, from
highest to lowest: BP_NODE_VERSION
, package.json
, .nvmrc
and .node-version
.
To configure the buildpack to use Node.js v12.12.0 when deploying your app, set the
following environment variable at build time, either directly (ex. pack build my-app --env BP_NODE_VERSION=12.12.0
) or through a
project.toml
file:
BP_NODE_VERSION="12.12.0"
Copied!
If your apps use npm
or yarn
, you can specify the Node.js version your apps use
during deployment by configuring the engines
field in the package.json
file. To configure the buildpack to use Node.js v12.12.0 when deploying your
app, include the values below in your package.json
file:
{ "engines": { "node": "12.12.0" } }
Copied!
For more information about the engines
configuration option in the
package.json
file, see the
engines section of the
npm-package.json topic in the NPM documentation.
Node Version Manager is a common option for managing the Node.js version an app
uses. To specify the Node.js version your apps use during deployment, include a
.nvmrc
file with the version number. For more information about the contents
of a .nvmrc
file, see .nvmrc in the
Node Version Manager repository on GitHub.
.node-version
is another common option that is compatible with Node.js version managers
such as asdf
and nodenv
. You can use a .node-version
file to set the Node.js version
that your apps use during deployment, according to one of the following formats:
12.12.0
Copied!
OR
v12.12.0
Copied!
OR
12.12
Copied!
Specifying the Node version through buildpack.yml
configuration will be deprecated in Node Engine Buildpack v1.0.0.
To migrate from using buildpack.yml
please set the $BP_NODE_VERSION
environment variable.
The Node.js CNB sets a number of environment variables during the build
and
launch
phases of the app lifecycle. The sections below describe each
environment variable and its impact on your app.
The MEMORY_AVAILABLE
environment variable reports the total amount of memory
available to the app. The Node.js CNB calculates this value from the limits
specified by the operating system in
/sys/fs/cgroup/memory/memory.limit_in_bytes
.
profile.d
launch
The NODE_ENV
environment variable specifies the environment in which the app
runs.
node-engine
buildpackbuild
The NODE_HOME
environment variable sets the path to the node
installation.
node-engine
buildpackbuild
node
installationThe NODE_VERBOSE
environment variable adjusts the amount of logging output
from NPM during installs.
node-engine
buildpackbuild
The NPM_CONFIG_LOGLEVEL
environment variable adjusts the level of logging NPM
uses.
npm-install
buildpackbuild
The NPM_CONFIG_PRODUCTION
environment variable installs only production
dependencies if NPM install is used.
npm-install
buildpackbuild
The node_modules/.bin
directory is appended onto the PATH
environment variable
yarn-install
or npm-install
buildpacksbuild
node_modules/.bin
directoryNode.js limits the total size of all objects on the heap. Enabling the
optimize-memory
feature sets this value to three-quarters of the total memory
available in the container. For example, if your app is limited to 1 GB
when pushed, the heap of your Node.js app is limited to 768 MB.
You can enable memory optimization through the BP_NODE_OPTIMIZE_MEMORY
environment variable.
BP_NODE_OPTIMIZE_MEMORY
Environment VariableTo enable memory optimization through the BP_NODE_OPTIMIZE_MEMORY
environment
variable, set it to true
.
pack build my-app \ --buildpack gcr.io/paketo-buildpacks/nodejs \ --env BP_NODE_OPTIMIZE_MEMORY=true
Copied!
Enabling memory optimization through your buildpack.yml
file will be
deprecated in Node Engine Buildpack v1.0.0. To migrate from using
buildpack.yml
please set the BP_NODE_OPTIMIZE_MEMORY
environment variable
mentioned above.
The Node.js CNB allows you to build a Node.js app that does not rely on any external packages. To detect whether for not the app is a Node.js app the Node.js app looks for one of the following files in your apps root directory:
server.js
app.js
main.js
index.js
The Node.js CNB will then set the start command to be node <detected file>
.
If you have multiples of these files in your apps root directory then the one
will be chosen based on a priority list which reflects the order of the list
above with server.js
being the highest priority and index.js
being the
lowest.
The BP_LAUNCHPOINT
environment variable may be used to specify a file for the
start command that is not included in the set of files the buildpack looks for
by default. The buildpack will verify that the file specified exists and then
use that as to set the start command. BP_LAUNCHPOINT
can be used as follows:
BP_LAUNCHPOINT=./src/launchpoint.js
Copied!
This will result in the following start command: node src/launchpoint.js
To specify a subdirectory to be used as the root of the app, please use the
BP_NODE_PROJECT_PATH
environment variable at build time either directly or
through a project.toml
.
This could be useful if your app is a part of a monorepo.
For example, if your project has the following structure:
.
├── go-app
│ ├── go.mod
│ └── main.go
└── node-app
├── file.js
├── index.js
└── package.json
you could then set the following at build time.
$BP_NODE_PROJECT_PATH=node-app
Many Node.js apps require a number of third-party libraries to perform common
tasks and behaviors. NPM is an option for managing these third-party
dependencies that the Node.js CNB fully supports. Including a package.json
file in your app source code triggers the NPM installation process. The sections
below describe the NPM installation process run by the buildpack.
NPM supports several distinct methods for installing your package dependencies.
Specifically, the Node.js CNB runs either the npm install
, npm rebuild
, or npm ci
commands to build your app
with the right set of dependencies. When deciding which installation process to
use, the Node.js CNB consults your app source code, looking for the presence of
specific files or directories. The installation process used also determines
how the Node.js CNB will reuse layers when rebuilding your app.
The table below shows the process the Node.js CNB uses to determine an installation process for NPM packages. When a combination of the files and directories listed in the table below are present in your app source code, the Node.js CNB uses an installation process that ensures the correct third-party dependencies are installed during the build process.
package-lock.json |
node_modules |
npm-cache |
Command |
---|---|---|---|
X | X | X | npm install |
X | X | ✓ | npm install |
X | ✓ | X | npm rebuild |
X | ✓ | ✓ | npm rebuild |
✓ | X | X | npm ci |
✓ | X | ✓ | npm ci |
✓ | ✓ | X | npm rebuild |
✓ | ✓ | ✓ | npm ci |
The following sections give more information about the files listed in the table above, including how to generate them, if desired.
The package-lock.json
file is generated by running npm install
. For
more information, see
npm-package-lock.json in the
NPM documentation.
The node_modules
directory contains vendored copies of all the packages
installed by the npm install
process. For more information, see the Node
Modules section of the
npm-folders topic in the NPM documentation.
The npm-cache
directory contains a content-addressable cache that stores all
HTTP-request- and package-related data. Additionally, including a cache ensures
that the app can be built entirely offline.
To populate an npm-cache
directory:
npm ci --cache npm-cache
Copied!
For more information about the NPM cache, see npm-cache in the NPM documentation.
To improve build times for apps, the Node.js CNB has a method for reusing the build results from previous builds. When the CNB determines that a portion of the build process can be reused from a previous build, the CNB uses the previous result. Each installation process uses a different method for determining whether the CNB can reuse a previous build result.
For npm install
, the CNB never reuses a node_modules
directory from previous builds.
For npm rebuild
, the CNB can reuse a node_modules
directory from a previous
build if the included node_modules
directory in the app source code has not
changed since the prior build.
For npm ci
, the CNB can reuse a node_modules
directory from a previous
build if the package-lock.json
file included in the app source code has not
changed since the prior build.
The Node.js CNB respects native configuration options for NPM. If you would
like to learn more about NPM native configuration please check the NPM
Configuration documentation
and the .npmrc
documentation.
As part of the build process, the Node.js CNB determines a start command for
your app. The start command differs depending on which package management
tooling the Node.js CNB uses. If the Node.js CNB uses npm
or yarn
to
install packages, the start command is generated from the contents of
package.json
.
Many Node.js apps require a number of third-party libraries to perform common
tasks and behaviors. Yarn is an alternative option to NPM for managing these
third-party dependencies. Including package.json
and yarn.lock
files in
your app source code triggers the Yarn installation process.
The Node.js CNB runs yarn install
and yarn check
to ensure that third-party
dependencies are properly installed.
The yarn.lock
file contains a fully resolved set of package dependencies that
Yarn manages. For more information, see
yarn.lock in the Yarn
documentation.
The Node.js CNB respects native configuration options for Yarn. If you would
like to learn more about Yarn configuration using .yarnrc
please visit the
Yarn documentation.
As part of the build process, the Node.js CNB determines a start command for
your app. The start command differs depending on which package management
tooling the Node.js CNB uses. If the Node.js CNB uses yarn
to install
packages, the start command is yarn start
.
The Node.js CNB also supports simple apps that do not require third-party packages.
If no package manager is detected, the Node.js CNB will set the start command
node server.js
. The app name is not currently configurable.
Node.js Buildpack users can provide their own CA certificates and have them included in the container root truststore at build-time and runtime by following the instructions outlined in the CA Certificates section of our configuration docs.
Node.js Buildpack users can set custom start processes for their app image by following the instructions in the Procfiles section of our configuration docs.
Node.js Buildpack users can embed launch-time environment variables in their app image by following the documentation for the Environment Variables Buildpack.
Node.js Buildpack users can add labels to their app image by following the instructions in the Applying Custom Labels section of our configuration docs.
The Node.js Buildpack runs fine on the Base builder for most apps. If your app
requires compilation of native extensions using node-gyp
, the buildpack requires that
you use the Full builder. This is because node-gyp
requires python
which is excluded from the
the Base builder, and the module may require other shared objects.
Last modified: April 8, 2021