Manage dependencies in Node.js

Node.js applications on the VIP Platform must use npm to manage their dependencies. Other dependency managers such as yarn are not supported. 

Installing dependencies

Prior to building and running a Node.js application, VIP installs the application’s production dependencies with: 

npm install --production 

This step installs the dependencies listed in the dependencies section of an application’s package.json . It does not install the dependencies listed in the devDependencies section.

Any dependency that is required to build or run an application on a VIP Platform environment—including build tools like Webpack or Sass—should be installed as a production dependency.

Production dependencies are installed and saved using the --save option:

npm install --save webpack 

For development dependencies, use the --save-dev option:

npm install --save-dev eslint

The VIP Platform currently runs npm install instead of npm clean-install (npm ci) when installing an application’s production dependencies. The npm install command will attempt to resolve any dependency conflicts between package.json and package-lock.json and is therefore less likely to fail. If needed, customers are encouraged to share requests for updates to this default behavior in VIP’s Feedback Portal.

Version management

Both package.json and package-lock.json should be committed to a wpcomvip GitHub repository. Providing package-lock.json enables every system, including the VIP platform, to install and use the exact same dependency tree.

VIP also supports npm-shrinkwrap.json. If npm-shrinkwrap.json is present, it takes precedence over package-lock.json. Though both files perform similar functions, the differences between npm-shrinkwrap.json and package-lock.json should be considered carefully before adding npm-shrinkwrap.json to an application.

When developing code locally, check that the dependencies installed locally match those specified by package-lock.json in the current working branch. If there are any discrepancies, or to just eliminate doubt, remove the node_modules directory entirely and reinstall the dependencies.

Private dependencies

Using private dependencies is not recommended because they can introduce issues that are difficult to troubleshoot. For example, if an authorization token used to load private dependencies is rotated or expires, builds may seem to fail spontaneously. Additionally, using private dependencies to manage application secrets does not impart any additional protection and may contribute to a false sense of security. Instead, environment variables can be used to more securely manage secrets.

If private dependencies are necessary, private npm packages can be used to load them:

1. Publish the private code as one or more private npm packages and install them as dependencies of the application.
2. Generate an npm access token that has permission to read the private packages.
3. Set an environment variable with the access token as its value.
4. Commit an .npmrc file that references the environment variable name:

# comments begin with # or ;
//registry.npmjs.org/:_authToken=${NPM_AUTH_TOKEN}

The token will be used by npm to install the private packages on the VIP platform. This approach can be used to install private packages from one or more custom registries by adding additional entries to the .npmrc file:

# official NPM registry
//registry.npmjs.org/:_authToken=${NPM_AUTH_TOKEN}

# myorg custom registry
@myorg:registry=https://example.com/myorg/
//example.com/myorg/:_authToken=${MYORG_NPM_AUTH_TOKEN}

Make sure to use the curly-brace notation when referencing environment variables; omitting them will fail silently. Also note that npm will not read environment variables from .env files.

Committing the authorization tokens directly to the application’s GitHub repository, either in .npmrc or in package.json, is not recommended.

Workspaces

Workspaces are an npm feature that allow projects to reference local code as modules. This is often leveraged in “monorepos” to develop subpackages that are maintained inside of a parent codebase. The VIP Platform supports workspaces when they are placed in a directory named packages/ in the root of the codebase. Using any other path or employing symlinks will result in a build failure at the npm install step.