link_js_package rule

Rules

Defines a node package that is linked into a node_modules tree as a direct dependency.

This is used in co-ordination with the link_js_package_store rule that links into the node_modules/.apsect_rules_js virtual store with a pnpm style symlinked node_modules output tree.

The term "package" is defined at https://nodejs.org/docs/latest-v16.x/api/packages.html

See https://pnpm.io/symlinked-node-modules-structure for more information on the symlinked node_modules structure. Npm may also support a symlinked node_modules structure called "Isolated mode" in the future: https://github.com/npm/rfcs/blob/main/accepted/0042-isolated-mode.md.

Example usage (generated)

load("@aspect_rules_js//js/private:link_js_package.bzl", "link_js_package_direct")

link_js_package_direct(
    # A unique name for this target.
    name = "",
    # The link_js_package target to link as a direct dependency.
    src = "",
)

A unique name for this target.

The link_js_package target to link as a direct dependency.


Defines a node package that is linked into a node_modules tree.

The node package is linked with a pnpm style symlinked node_modules output tree.

The term "package" is defined at https://nodejs.org/docs/latest-v16.x/api/packages.html

See https://pnpm.io/symlinked-node-modules-structure for more information on the symlinked node_modules structure. Npm may also support a symlinked node_modules structure called "Isolated mode" in the future: https://github.com/npm/rfcs/blob/main/accepted/0042-isolated-mode.md.

Example usage (generated)

load("@aspect_rules_js//js/private:link_js_package.bzl", "link_js_package_store")

link_js_package_store(
    # A unique name for this target.
    name = "",
    # A js_package target or or any other target that provides a JsPackageInfo
    src = "",
)

A unique name for this target.

Other node packages this one depends on.

This should include all modules the program may need at runtime.

In typical usage, a node.js program sometimes requires modules which were never declared as dependencies. This pattern is typically used when the program has conditional behavior that is enabled when the module is found (like a plugin) but the program also runs without the dependency.

This is possible because node.js doesn't enforce the dependencies are sound. All files under node_modules are available to any program. In contrast, Bazel makes it possible to make builds hermetic, which means that all dependencies of a program must be declared when running in Bazel's sandbox.

The package name to link to.

If unset, the package name in the JsPackageInfo src must be set. If set, takes precendance over the package name in the JsPackageInfo src.

A js_package target or or any other target that provides a JsPackageInfo.

The package version being linked.

If unset, the package version in the JsPackageInfo src must be set. If set, takes precendance over the package version in the JsPackageInfo src.


Macros and Functions

"Links a package to the virtual store if in the root package and directly to node_modules if direct is True.

When called at the root_package, a virtual store target is generated named "link__{bazelified_name}__store".

When linking direct, a "{name}" alias is generated which consists of the direct node_modules link and transitively its virtual store link and the virtual store links of the transitive closure of deps.

When linking direct, "{name}__dir" alias is also generated that refers to a directory artifact can be used to access the package directory for creating entry points or accessing files in the package.

Example usage (generated)

load("@aspect_rules_js//js/private:link_js_package.bzl", "link_js_package")

link_js_package(
    # The name of the package
    name = "",
)

The name of the package. This should generally by the same as

the root package where the node_modules virtual store is linked to

whether or not to link a direct dependency in this package For 3rd party deps fetched with an npm_import, direct may not be specified if link_packages is set on the npm_import.

the js_package target to link; may only to be specified when linking in the root package

list of link_js_package_store; may only to be specified when linking in the root package

whether or not to fail if this is called in a package that is not the root package and with direct false

the visibility of the generated targets

see attributes of link_js_package_store rule


Returns the label to the link_js_package store for a package.

This can be used to generate virtual store target names for the deps list of a link_js_package.

Example root BUILD.file where the virtual store is linked by default,

load("@npm//:defs.bzl", "link_js_packages")
load("@aspect_rules_js//:defs.bzl", "link_js_package")

# Links all packages from the `translate_pnpm_lock(name = "npm", pnpm_lock = "//:pnpm-lock.yaml")`
# repository rule.
link_js_packages()

# Link a first party `@lib/foo` defined by the `js_package` `//lib/foo:foo` target.
link_js_package(
    name = "link_lib_foo",
    src = "//lib/foo",
)

# Link a first party `@lib/bar` defined by the `js_package` `//lib/bar:bar` target
# that depends on `@lib/foo` and on `acorn` specified in `package.json` and fetched
# with `translate_pnpm_lock`
link_js_package(
    name = "link_lib_bar",
    src = "//lib/bar",
    deps = [
        link_js_package_dep("link_lib_foo"),
        link_js_package_dep("acorn", version = "8.4.0"),
    ],
)

Example usage (generated)

load("@aspect_rules_js//js/private:link_js_package.bzl", "link_js_package_dep")

link_js_package_dep(
    # The name of the link target
    name = "",
)

The name of the link target. For first-party packages, this must match the name passed to link_js_package for the package in the root package when not linking at the root package.

For 3rd party deps fetched with an npm_import or via a translate_pnpm_lock repository rule, the name must match the package attribute of the corresponding npm_import. This is typically the npm package name.

The version of the package This should be left unset for first-party packages linked manually with link_js_package.

For 3rd party deps fetched with an npm_import or via a translate_pnpm_lock repository rule, the package version is required to qualify the dependency. It must the version attribute of the corresponding npm_import.

The bazel package of the virtual store. Defaults to the current package


Example usage (generated)

load("@aspect_rules_js//js/private:link_js_package.bzl", "link_js_package_direct_lib")

link_js_package_direct_lib.implementation(
    ctx = None,
)

Example usage (generated)

load("@aspect_rules_js//js/private:link_js_package.bzl", "link_js_package_store_lib")

link_js_package_store_lib.implementation(
    ctx = None,
)