Question about generated link_js_packages and link_* functions about rules_js HOT 1 CLOSED

The documentation is still lacking some of the details for sure. Now that most of the implementation is done for an alpha release we'll be adding a lot more to the docs in the next few weeks. In the meantime, I'll try to explain as succinctly as I can here.

First for context, after a team public API review and resulting refactoring, the generated link_js_packages() is now called npm_link_all_packages and takes a name parameter so the call will typically look like,

load("@npm//:defs.bzl", "npm_link_all_packages")

npm_link_all_packages(name = "node_modules")

link_js_package has been renamed to npm_link_package.

link_PKG_NAME was a user-space name. There was an overloaded load statement link_acorn = "link_js_package". This has since been renamed to npm_link_acorn and now also takes a name parameter.

load("@acorn__8.4.0__links//:defs.bzl", npm_link_acorn = "npm_link_package")

npm_link_acorn(name = "node_modules/acorn")

npm_link_acorn is an example of syntax de-sugaring for users who want to use the npm_import repository rule directly instead of npm_translate_lock with a pnpm lock file (npm_translate_lock(pnpm_lock = "//:pnpm-lock.yaml")),

# As an example, manually import a package using explicit coordinates.
# Just a demonstration of the syntax de-sugaring.
npm_import(
    name = "acorn__8.4.0",
    integrity = "sha512-ULr0LDaEqQrMFGyQ3bhJkLsbtrQ8QibAseGZeaSUiT/6zb9IvIkomWHJIvgvwad+hinRAgsI51JcWk2yvwyL+w==",
    package = "acorn",
    version = "8.4.0",
)

Most users will have a happier path by using npm_translate_lock for all their 3rd party deps and never need to write an npm_import directly.

TL;DR for the "link" rules is that they accomplish the same goal as the "link" phases in the npm, yarn & pnpm package managers, which is to lay out a node_modules on disk for tools to find.

Unlike rules_nodejs, where we ran yarn install and npm_install in repository rules and then symlinked a node_modules tree at runtime in the nodejs_binary launcher, in rules_js the node_modules tree is built by many build actions defined by the "link" rules and lives in the bazel output tree. The is no more runtime dynamic linker. This means that the "link" targets that build this tree must go in the BUILD files of the packages where the node_modules trees should be in the user's workspace. This is why the npm_link_all_packages and npm_link_package targets must be there and not in BUILD files in an external repository.

If you bazel query in rules_js you'll see these link targets show up,

//examples/npm_deps:node_modules
//examples/npm_deps:node_modules/@rollup
//examples/npm_deps:node_modules/@rollup/plugin-commonjs
//examples/npm_deps:node_modules/@rollup/plugin-commonjs/dir
//examples/npm_deps:node_modules/mobx
//examples/npm_deps:node_modules/mobx-react
//examples/npm_deps:node_modules/mobx-react/dir
//examples/npm_deps:node_modules/mobx/dir
//examples/npm_deps:node_modules/react
//examples/npm_deps:node_modules/react/dir
//examples/npm_deps:node_modules/rollup
//examples/npm_deps:node_modules/rollup/dir
//examples/npm_deps:node_modules/uvu
//examples/npm_deps:node_modules/uvu/dir

The labels are typically node_modules/* by convention but users could name them differently using the name attribute of the link targets.

An important implementation detail of how we currently link is that we link a pnpm-style virtual store into the "root" package (the package where the pnpm lock file lives). If you bazel query rules_js you'll see these these targets in the root BUILD file,

//:store_link__acorn__8.4.0
//:store_link__acorn__8.4.0__dir
//:store_link__acorn__8.4.0__pkg
//:store_link__acorn__8.4.0__ref

In theory we could link in a yarn or npm style in the future to give users more options. We opted for the pnpm-style symlinked node_modules tree for 1.0 since we could make npm deps lazy fetched, meaning you don't need to fetch an individual npm dependency from the registry when you build (once you have a lock file generated) unless it is used by a target you are building. This is not as easily done with the way yarn and npm link. If we add the option to use yarn and npm lock files in the future, it would most likely not allow for lazy npm deps.

For users that have 3rd party deps and 1st party deps expressed in their pnpm workspace & pnpm lock file, calling npm_link_all_packages(name = "node_modules") in the package that has the lock file & in any workspace packages where there should be a linked node_modules will be the happy path to link everything.

Some users may have all their 3rd party deps expressed in their pnpm lock file and link these with npm_link_all_packages(name = "node_modules") but opt to not use workspaces for first-party deps and instead manually call npm_link_package for first party deps.

Other users may have 3rd party deps expressed in their pnpm lock file and not link 1st party-deps at all but instead use path mappings in tsconfig and other tools for resolving those by a package name such as @mycorp/mylib or just resolve them with relative imports ../../../path/to/mylib or path-mapped absolute imports /mycrop/path/to/my/lib. In those cases, 1st party deps would not be linked into node_modules at all.

from rules_js.