aspect-build/rules_js

rules_js is a high-performance Bazel integration for JavaScript based on the pnpm package manager. It is designed to be:

• Lazy: Only fetches and installs npm packages required for the specific build or test targets requested.
• Correct: Provides seamless Node.js module resolution, resolving common issues like TypeScript rootDirs path mapping.
• Fast: Uses Bazel's sandbox to treat npm packages as directories rather than individual files, significantly improving performance.
• Workspace-aware: Supports npm workspaces for managing nested packages in monorepos.

The npm_translate_lock rule allows you to use Yarn lockfiles within a Bazel workspace by translating them into a format compatible with rules_js. When using this rule, you can configure the following attributes:

• package_json: Specifies the package.json file.
• yarn_lock: Specifies the yarn.lock file.
• npmrc: Specifies the .npmrc configuration file.

This enables rules_js to resolve dependencies from a Yarn-based environment.

# Example attribute usage (conceptual)
npm_translate_lock(
    name = "my_translated_lockfile",
    package_json = "package.json",
    yarn_lock = "yarn.lock",
    npmrc = ".npmrc",
)

If you are migrating from the unmaintained build_bazel_rules_nodejs, rules_js is the recommended replacement. While they share the rules_nodejs core toolchain and providers, the higher layers differ significantly:

You can use the npm_package(root_paths) rule to generate multiple distinct npm packages from the same source by specifying different root_paths. This is useful when you want to create different distribution versions or subsets of a package based on specific directory structures.

# Conceptual usage of npm_package with different root_paths

npm_package(
    name = "pkg_c1",
    root_paths = ["path/to/subset_1"],
    # ... other attributes
)

npm_package(
    name = "pkg_c2",
    root_paths = ["path/to/subset_2"],
    # ... other attributes
)

rules_js is designed to model npm package dependency handling by closely mimicking pnpm.

Instead of Bazel performing its own resolution, it relies on a non-Bazel tool (typically pnpm) to resolve version constraints and determine the node_modules structure. This information is encoded in a pnpm-lock.yaml file. Bazel then uses this lockfile to create npm_import rules, allowing Bazel's downloader to fetch packages individually with integrity hashes for supply-chain security. This approach is highly performant because Bazel only fetches the specific packages required for the targets being analyzed.

When representing first-party packages in Bazel, prefer using js_library (or any rule providing JsInfo) over npm_package (which provides NpmPackageInfo).

JsInfo allows rules_js to pass through the provider without collecting the full package content until an action actually requests it. In contrast, NpmPackageInfo requires building the full package content to output a single directory artifact, which is slower.

In a Bazel workspace using rules_js, you can define dependencies between local packages using the workspace:* protocol in your package.json files. When you use npm_link_all_packages, Bazel automatically resolves these workspace references and links the packages together, allowing them to be treated as dependencies within the Bazel build graph.

{
  "dependencies": {
    "@mycorp/pkg-a": "workspace:*"
  }
}