This documentation explains how to use the Paketo Node.js Buildpack to build applications for several common use-cases. For more in-depth description of the buildpack’s behavior and configuration see the Paketo Node.js Buildpack Reference documentation.
To build a sample app locally with this buildpack using the pack CLI, run
git clone https://github.com/paketo-buildpacks/samples cd samples/nodejs/npm pack build my-app --buildpack paketo-buildpacks/nodejs \ --builder paketobuildpacks/builder-jammy-base
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 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 on the Paketo Node Engine
component buildpack’s releases page.
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"
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"
}
}
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
OR
v12.12.0
OR
12.12
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.
Node.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
at run time, 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 Variable
To enable memory optimization through the BP_NODE_OPTIMIZE_MEMORY environment
variable, set it to true.
pack build my-app \ --buildpack paketo-buildpacks/nodejs \ --env BP_NODE_OPTIMIZE_MEMORY=true
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.
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
To specify a script or series of scripts to run during build phase, please use the
BP_NODE_RUN_SCRIPTS environment variable at build time either directly or through a
project.toml. This
could be useful if your app uses a framework like Angular, React, or Vue where you need to run
scripts to build your app into a production state.
For example, if your project’s package.json has the following scripts:
{
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"lint": "eslint src/**/*.js src/**/*.jsx",
}
}
and your environment variable was set:
$BP_NODE_RUN_SCRIPTS=lint,build
then the lint and then build scripts would be run via npm or yarn, during build phase. Note that the
value for BP_NODE_RUN_SCRIPTS must be a comma separated list of script names.
By default, when an Angular app starts up, it attempts to create a cache,
.angular/cache, in the app’s directory. On some stacks, (including the Paketo
Jammy stacks) the app directory is read-only at runtime. As a result, Angular
apps will fail to start with errors like Error: EACCES: permission denied, open '/workspace/.angular/cache.
To avoid this failure, configure Angular to create the cache in a writeable
location, like /tmp.
angular.json
To configure the location of the Angular cache, set the cli.cache.path
parameter in your app’s angular.json. Add the following snippet to your
angular.json:
"cli":{
"cache": {
"path": "/tmp/.angular/cache"
}
},
With this setting, the Angular app will start successfully and write cache
artifacts to the /tmp directory.
The Node.js buildpack can detect automatically if an app requires npm.
The Node.js buildpack 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.
.npmrc
Adding an .npmrc file in your app’s working directory will allow you to provide
project-level npm configuration.
.npmrc
Some users may prefer not to include an .npmrc file in their source code
and app image (e.g. if an .npmrc contains credentials for connecting
to a private registry). The .npmrc can be provided via a service binding
whose type is npmrc. The binding must contain a file called .npmrc.
The Node.js Buildpack will set this binding as the NPM_CONFIG_GLOBALCONFIG in
the build environment.
To pack build with the binding:
pack build myapp \
--env SERVICE_BINDING_ROOT=/bindings \
--volume <absolute-path-to-binding-dir>:/bindings/npmrc
The Node.js buildpack can detect automatically if an app requires yarn, by
checking for a yarn.lock file.
The Node.js buildpack respects native configuration options for Yarn. If you would
like to learn more about Yarn configuration using .yarnrc please visit the
Yarn documentation.
.yarnrc
Adding an .yarnrc file in your app’s working directory will allow you to provide
project-level yarn configuration.
.yarnrc
Some users may prefer not to include an .yarnrc file in their source code
and app image. The .yarnrc can be provided via a service binding
whose type is yarnrc. The binding must contain a file called .yarnrc.
The Node.js Buildpack will set this binding as the user-level .yarnrc in
the build environment. It will not be present in the launch environment.
To pack build with the binding:
pack build myapp \
--env SERVICE_BINDING_ROOT=/bindings \
--volume <absolute-path-to-binding-dir>:/bindings/yarnrc
When building with the pack CLI, specify the latest Paketo Full Builder at build time
with the --builder flag.
pack build my-app --builder paketobuildpacks/builder-jammy-full
The Node.js buildpack supports building apps without node_modules or a package.json.
It will detect this type of app automatically, by looking for one of these four files in
the root of your application directory:
server.jsapp.jsmain.jsindex.jsIf your app’s entrypoint file is not one of the four files named above,
you can specify a different file name (or path) by setting the BP_LAUNCHPOINT
environment variable at build time.
BP_LAUNCHPOINT can be set as follows:
BP_LAUNCHPOINT="./src/launchpoint.js"
The image produced by the build will run node src/launchpoint.js
as its start command.
If you are using a framework that generates a static site from JavaScript source code (e.g. React, Vue, Angular), you can use the Paketo Web Servers buildpack to build the static assets and automatically configure a web server. The Web Servers documentation covers this use case.
By default, your Node.js server will be the only process running in your app container at runtime. You can enable restarting the server process when files in the app’s working directory change, which may facilitate a shorter feedback loop for iterating on code changes. This feature may be used in conjunction with a dev orchestrator like Tilt.
BP_LIVE_RELOAD_ENABLED
To enable reloadable processes, set the $BP_LIVE_RELOAD_ENABLED environment
variable at build time, either by passing a flag to the
platform or by
adding it to your project.toml. See the Cloud Native Buildpacks
documentation to learn more about project.toml files.
pack build flag
pack build myapp --env BP_LIVE_RELOAD_ENABLED=true
project.toml file
[ _ ] schema-version = "0.2" [[ io.buildpacks.build.env ]] name = 'BP_LIVE_RELOAD_ENABLED' value = 'true'
Tiltfile with the pack resource
You can use the Paketo Node.js buildpack with Tilt. This example
uses the pack extension for Tilt.
pack('my-app',
buildpacks=["paketo-buildpacks/nodejs"],
env_vars=["BP_LIVE_RELOAD_ENABLED=true"],
live_update=[
sync('.', '/workspace'),
]
)
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.
DEBUG logging
Users of the Node.js buildpack can access extra debug logs during the image build process by setting the BP_LOG_LEVEL
environment variable to DEBUG at build time. Additional debug logs will
appear in build logs if the relevant buildpacks have debug log lines.
pack build my-app --buildpack paketo-buildpacks/nodejs \ --env BP_LOG_LEVEL=DEBUG
Last modified: April 3, 2024