​
Overview

This documentation is adapted for Miget purposes and is based on information from the Paketo Node.js Buildpack documentation.
This documentation explains how to use the Paketo buildpacks with Miget to build Node.js applications for several common use-cases. For more in-depth description of the buildpacks’ behavior and configuration see the Paketo Node.js Buildpack. For more in-depth description of the buildpack’s behavior and configuration see the Paketo Node.js Buildpack Reference documentation. If your intention is to deploy an app using a Dockerfile, please refer to the Dockerfile page for guidance and best practices.

​
Prerequisites

The pack CLI is used throughout the examples. Examples assume that the Paketo Base builder is the default builder: 
$ pack config default-builder paketobuildpacks/builder-jammy-base

​
Example App

A demo instance of this app is hosted at node-js.onmiget.com.

​
Build

$ git clone git@github.com:migetapp/node-js-hello-world.git
$ cd node-js-hello-world
$ pack build node-js-hello-world

​
Run

$ docker run -p 5000:5000 -e PORT=5000 node-js-hello-world
The example app should now be running on localhost:5000.

​
Install a Specific Node Engine Version

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.

​
Using BP_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 or through a project.toml file: Environment Variable set under Settings -> Variables: BP_NODE_VERSION="12.12.0"

​
Using package.json

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.

​
Using .nvmrc

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.

​
Using .node-version

.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

​
Enable Heap Memory Optimization

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. To enable memory optimization through the BP_NODE_OPTIMIZE_MEMORY environment variable, set it to true. Environment Variable set under Settings -> Variables: BP_NODE_OPTIMIZE_MEMORY="true"

​
Build an App From Source in a Subdirectory

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

​
Run Scripts During Build Phase

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.

​
Build Angular apps on stacks with read-only file systems

By default, when an Angular app starts up, it attempts to create a cache, .angular/cache, in the app’s directory. At Miget 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.

​
Setting an Angular cache path in 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.

​
Build an App that Uses NPM

The Node.js buildpack can detect automatically if an app requires npm.

​
Configure NPM During the Build

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.

​
Project-level .npmrc

Adding an .npmrc file in your app’s working directory will allow you to provide project-level npm configuration.

​
Global .npmrc

This isn’t yet fully supported at Miget. We are working on mouting Miget Volumes for the builder environment
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 build at Miget with the binding, you need to create a Volume as /bindings and store your credential there. Next, add Variable under Settings -> Variables: SERVICE_BINDING_ROOT=/bindings

​
Build an App that Uses Yarn

The Node.js buildpack can detect automatically if an app requires yarn, by checking for a yarn.lock file.

​
Configure Yarn During the Build

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.

​
Project-level .yarnrc

Adding an .yarnrc file in your app’s working directory will allow you to provide project-level yarn configuration.

​
User-level .yarnrc

This isn’t yet fully supported at Miget. We are working on mouting Miget Volumes for the builder environment
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 build at Miget with the binding, you need to create a Volume as /bindings and store your credential there. Next, add Variable under Settings -> Variables: SERVICE_BINDING_ROOT=/bindings

​
Build an App Without Package Management

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.js
  • app.js
  • main.js
  • index.js

​
Specify A Custom Entrypoint

If 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.

​
Using BP_LAUNCHPOINT

Environment Variable set under Settings -> Variables: BP_LAUNCHPOINT="./src/launchpoint.js" The image produced by the build will run node src/launchpoint.js as its start command.

​
Build and Serve a Frontend Framework App

If you are using a framework that generates a static site from JavaScript source code (e.g. React, Vue, Angular), you can use the Web Servers buildpack to build the static assets and automatically configure a web server.

​
Enable Process Reloading

This isn’t currently available at Miget. We are working on it.

​
Override the Start Process Set by the Buildpack

This isn’t currently available at Miget. We are working on it.

​
Enable 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. Environment Variable set under Settings -> Variables: BP_LOG_LEVEL=DEBUG