This is a plugin to integrate Node.js with Pants.
Node.js targets in Pants are designed to work with existing Node.js package management tools and their configuration files. The node_module target type uses a package.json file in the same directory as its definition. It combines dependencies declared on the target in the BUILD file with the original package.json to form a complete package.json that can be used to run tasks on the target through Pants.
node_module: A node module target.
node_preinstalled_module: A prebuilt node_module that will be downloaded during resolve step.
node_bundle: A bundle of node modules.
node_remote_module: Remote third party module. [Not recommended, instead specify dependencies in package.json with lock file]
There is limited support for linting and formatting using the
fmt goals, which use
eslint global rules will need to be configured by the repo owner
Source level dependencies
Source-level dependencies are currently supported within the
yarn package manager. To specify a target-level dependency on
another node_module target, you must:
Specify the local dependency using the
file:specifier following npm rules within the
package.jsonwith relative path to the target dependency
The dependent target must have a valid target definition and package.json with the same package name as specified in the
In the BUILD definition, the node_module target must also specify the fully qualified pants target address for each
file:dependency. (In the future, with dep inference, this step may no longer be necessary).
Scopes normally defined in the the
namefield of the
package.jsonfile needs to be replicated in the BUILD definition in the
With some caveats,
Peer dependencies cannot be resolved within source dependencies. The source dependencies are symlinked and do not have a direct relationships with the parent target. There may be duplicate dependencies since there is no flattening of the dependency graph.
Source dependencies can only be specified in the “dependencies” field.
Source dependencies need to match 1:1 with package dependencies, but cannot currently express the node_scope within that context. The node_scope is assumed through the
node_scopefield in the BUILD definition.
See the examples directory for real examples.
Pants will bootstrap itself with its own copy of Node.js, NPM, and Yarn package manager and use them to run commands. It runs those commands with the bootstrapped Node's bin directory at the front of the PATH.
Distribution versions can be modified in
There are two supported package management tools: NPM and Yarn. You can specify which package manager is used to
your dependencies in your BUILD target definition.
NPM 5.0+ and Yarn both support locking dependencies to specific versions through the
yarn.lock files respectively.
To ensure determinism and reproducibility within Pants, these files should be checked into your repository and included in the
target definition's sources argument.
Pants can install Node modules into the source definition directory with
./pants node-install [target]
You can install all types of node_module targets. Pants effectively walks forward from
the edges of the dependency tree topological sort for a target and does an "install"
for each target it encounters along the way. Pants then symlinks each of the source dependencies
in the correct path under the
Pants can run tests defined in your
package.json file similar to your vanilla package manager.
The main difference is that the tests are executed within Pants' virtual environment.
node_test targets are able to run scripts defined in the
When Pants executes a
node_test target, the target's sources are copied into place under the working directory. The
sources are then
installed into the pants working directory. The targets and paths are cached
and passed into the Node.js runtime as NODE_PATH parameters to execute your test.
Resolve is a task that helps Pants install and keep track of node_module targets.
node_remote_module dependencies are installed from the remote source, and
node_module dependencies are installed via
paths to previously-installed targets under the working directory.
./pants repl [target] lets you run Node in REPL mode from the resolved target's path under the
REPL only works with npm package manager.
The examples directory contains a few types of interdependent JS projects.
- A server project transpiled using Babel in its prepublish step
- A web build tool encapsulating Webpack and a set of loaders
- A web component (button) using React and CSS in a separate file, built with the web build tool, containing its own test file
- A web project using React, built with the web build tool, depending on the server project and button component, and containing its own test file
- A yarn workspace project using source-level dependencies in two ways. (Workspaces and pants). Source-level dependencies does not need Yarn Workspaces.