npm_translate_lock.md

Repository rule to fetch npm packages for a lockfile.

Load this with,

load("@aspect_rules_js//npm:repositories.bzl", "npm_translate_lock")

These use Bazel's downloader to fetch the packages. You can use this to redirect all fetches through a store like Artifactory.

See https://blog.aspect.build/configuring-bazels-downloader for more info about how it works and how to configure it.

npm_translate_lock is the primary user-facing API. It uses the lockfile format from pnpm because it gives us reliable semantics for how to dynamically lay out node_modules trees on disk in bazel-out.

To create pnpm-lock.yaml, consider using pnpm import to preserve the versions pinned by your existing package-lock.json or yarn.lock file.

If you don't have an existing lock file, you can run npx pnpm install --lockfile-only.

Advanced users may want to directly fetch a package from npm rather than start from a lockfile, npm_import does this.

list_patches

list_patches(name, out, include_patterns, exclude_patterns)

Write a file containing a list of all patches in the current folder to the source tree.

Use this together with the verify_patches attribute of npm_translate_lock to verify that all patches in a patch folder are included. This macro stamps a test to ensure the file stays up to date.

PARAMETERS

Name	Description	Default Value
name	Name of the target	none
out	Name of file to write to the source tree. If unspecified, name is used	None
include_patterns	Patterns to pass to a glob of patch files	["*.diff", "*.patch"]
exclude_patterns	Patterns to ignore in a glob of patch files	[]

npm_translate_lock

npm_translate_lock(name, pnpm_lock, npm_package_lock, yarn_lock, update_pnpm_lock,
                   node_toolchain_prefix, yq_toolchain_prefix, preupdate, npmrc, use_home_npmrc, data,
                   patches, patch_args, custom_postinstalls, package_visibility, prod,
                   public_hoist_packages, dev, no_optional, run_lifecycle_hooks, lifecycle_hooks,
                   lifecycle_hooks_envs, lifecycle_hooks_exclude,
                   lifecycle_hooks_execution_requirements, lifecycle_hooks_no_sandbox,
                   lifecycle_hooks_use_default_shell_env, replace_packages, bins,
                   verify_node_modules_ignored, verify_patches, quiet,
                   external_repository_action_cache, link_workspace, pnpm_version, use_pnpm,
                   npm_package_target_name, kwargs)

Repository macro to generate starlark code from a lock file.

In most repositories, it would be an impossible maintenance burden to manually declare all of the npm_import rules. This helper generates an external repository containing a helper starlark module repositories.bzl, which supplies a loadable macro npm_repositories. That macro creates an npm_import for each package.

The generated repository also contains:

• A defs.bzl file containing some rules such as npm_link_all_packages, which are documented here.
• BUILD files declaring targets for the packages listed as dependencies or devDependencies in package.json, so you can declare dependencies on those packages without having to repeat version information.

This macro creates a pnpm external repository, if the user didn't create a repository named "pnpm" prior to calling npm_translate_lock. rules_js currently only uses this repository when npm_package_lock or yarn_lock are used. Set pnpm_version to None to inhibit this repository creation.

For more about how to use npm_translate_lock, read pnpm and rules_js.

PARAMETERS

Name	Description	Default Value
name	The repository rule name	none
pnpm_lock	The pnpm-lock.yaml file.	None
npm_package_lock	The package-lock.json file written by npm install. Only one of npm_package_lock or yarn_lock may be set.	None
yarn_lock	The yarn.lock file written by yarn install. Only one of npm_package_lock or yarn_lock may be set.	None
update_pnpm_lock	When True, the pnpm lock file will be updated automatically when any of its inputs have changed since the last update. Defaults to True when one of npm_package_lock or yarn_lock are set. Otherwise it defaults to False. Read more: using update_pnpm_lock	False
node_toolchain_prefix	the prefix of the node toolchain to use when generating the pnpm lockfile.	"nodejs"
yq_toolchain_prefix	the prefix of the yq toolchain to use for parsing the pnpm lockfile.	"yq"
preupdate	Node.js scripts to run in this repository rule before auto-updating the pnpm lock file. Scripts are run sequentially in the order they are listed. The working directory is set to the root of the external repository. Make sure all files required by preupdate scripts are added to the data attribute. A preupdate script could, for example, transform resolutions in the root package.json file from a format that yarn understands such as @foo/**/bar to the equivalent @foo/*>bar that pnpm understands so that resolutions are compatible with pnpm when running pnpm import to update the pnpm lock file. Only needed when update_pnpm_lock is True. Read more: using update_pnpm_lock	[]
npmrc	The .npmrc file, if any, to use. When set, the .npmrc file specified is parsed and npm auth tokens and basic authentication configuration specified in the file are passed to the Bazel downloader for authentication with private npm registries. In a future release, pnpm settings such as public-hoist-patterns will be used.	None
use_home_npmrc	Use the $HOME/.npmrc file (or $USERPROFILE/.npmrc when on Windows) if it exists. Settings from home .npmrc are merged with settings loaded from the .npmrc file specified in the npmrc attribute, if any. Where there are conflicting settings, the home .npmrc values will take precedence. WARNING: The repository rule will not be invalidated by changes to the home .npmrc file since there is no way to specify this file as an input to the repository rule. If changes are made to the home .npmrc you can force the repository rule to re-run and pick up the changes by running: bazel run @{name}//:sync where name is the name of the npm_translate_lock you want to re-run. Because of the repository rule invalidation issue, using the home .npmrc is not recommended. .npmrc settings should generally go in the npmrc in your repository so they are shared by all developers. The home .npmrc should be reserved for authentication settings for private npm repositories.	None
data	Data files required by this repository rule when auto-updating the pnpm lock file. Only needed when update_pnpm_lock is True. Read more: using update_pnpm_lock	[]
patches	A map of package names or package names with their version (e.g., "my-package" or "[email protected]") to a label list of patches to apply to the downloaded npm package. Multiple matches are additive. These patches are applied after any patches in pnpm.patchedDependencies. Read more: patching	{}
patch_args	A map of package names or package names with their version (e.g., "my-package" or "[email protected]") to a label list arguments to pass to the patch tool. The most specific match wins. Read more: patching	{"*": ["-p0"]}
custom_postinstalls	A map of package names or package names with their version (e.g., "my-package" or "[email protected]") to a custom postinstall script to apply to the downloaded npm package after its lifecycle scripts runs. If the version is left out of the package name, the script will run on every version of the npm package. If a custom postinstall scripts exists for a package as well as for a specific version, the script for the versioned package will be appended with && to the non-versioned package script. For example, custom_postinstalls = { "@foo/bar": "echo something > somewhere.txt", "[email protected]": "echo something_else > somewhere_else.txt", }, Custom postinstalls are additive and joined with && when there are multiple matches for a package. More specific matches are appended to previous matches.	{}
package_visibility	A map of package names or package names with their version (e.g., "my-package" or "[email protected]") to a visibility list to use for the package's generated node_modules link targets. Multiple matches are additive. If there are no matches then the package's generated node_modules link targets default to public visibility (["//visibility:public"]).	{}
prod	If True, only install dependencies but not devDependencies.	False
public_hoist_packages	A map of package names or package names with their version (e.g., "my-package" or "[email protected]") to a list of Bazel packages in which to hoist the package to the top-level of the node_modules tree when linking. This is similar to setting https://pnpm.io/npmrc#public-hoist-pattern in an .npmrc file outside of Bazel, however, wild-cards are not yet supported and npm_translate_lock will fail if there are multiple versions of a package that are to be hoisted. public_hoist_packages = { "@foo/bar": [""] # link to the root package in the WORKSPACE "[email protected]": ["some/sub/package"] }, List of public hoist packages are additive when there are multiple matches for a package. More specific matches are appended to previous matches.	{}
dev	If True, only install devDependencies	False
no_optional	If True, optionalDependencies are not installed. Currently npm_translate_lock behaves differently from pnpm in that is downloads all optionaDependencies while pnpm doesn't download optionalDependencies that are not needed for the platform pnpm is run on. See pnpm/pnpm#3672 for more context.	False
run_lifecycle_hooks	Sets a default value for lifecycle_hooks if * not already set. Set this to False to disable lifecycle hooks.	True
lifecycle_hooks	A dict of package names to list of lifecycle hooks to run for that package. By default the preinstall, install and postinstall hooks are run if they exist. This attribute allows the default to be overridden for packages to run prepare. List of hooks are not additive. The most specific match wins. Read more: lifecycles	{}
lifecycle_hooks_envs	Environment variables set for the lifecycle hooks actions on npm packages. The environment variables can be defined per package by package name or globally using "*". Variables are declared as key/value pairs of the form "key=value". Multiple matches are additive. Read more: lifecycles	{}
lifecycle_hooks_exclude	A list of package names or package names with their version (e.g., "my-package" or "[email protected]") to not run any lifecycle hooks on. Equivalent to adding <value>: [] to lifecycle_hooks. Read more: lifecycles	[]
lifecycle_hooks_execution_requirements	Execution requirements applied to the preinstall, install and postinstall lifecycle hooks on npm packages. The execution requirements can be defined per package by package name or globally using "*". Execution requirements are not additive. The most specific match wins. Read more: lifecycles	{}
lifecycle_hooks_no_sandbox	If True, a "no-sandbox" execution requirement is added to all lifecycle hooks unless overridden by lifecycle_hooks_execution_requirements. Equivalent to adding "*": ["no-sandbox"] to lifecycle_hooks_execution_requirements. This defaults to True to limit the overhead of sandbox creation and copying the output TreeArtifacts out of the sandbox. Read more: lifecycles	True
lifecycle_hooks_use_default_shell_env	The use_default_shell_env attribute of the lifecycle hooks actions on npm packages. See use_default_shell_env Note: --incompatible_merge_fixed_and_default_shell_env is often required and not enabled by default in Bazel < 7.0.0. This defaults to False reduce the negative effects of use_default_shell_env. Requires bazel-lib >= 2.4.2. Read more: lifecycles	{}
replace_packages	A dict of package names to npm_package targets to link instead of the sources specified in the pnpm lock file for the corresponding packages. The injected npm_package targets may optionally contribute transitive npm package dependencies on top of the transitive dependencies specified in the pnpm lock file for their respective packages, however, these transitive dependencies must not collide with pnpm lock specified transitive dependencies. Any patches specified for the packages will be not applied to the injected npm_package targets. They will be applied, however, to the fetches sources for their respecitve packages so they can still be useful for patching the fetched package.json files, which are used to determine the generated bin entries for packages. NB: lifecycle hooks and custom_postinstall scripts, if implicitly or explicitly enabled, will be run on the injected npm_package targets. These may be disabled explicitly using the lifecycle_hooks attribute.	{}
bins	Binary files to create in node_modules/.bin for packages in this lock file. For a given package, this is typically derived from the "bin" attribute in the package.json file of that package. For example: bins = { "@foo/bar": { "foo": "./foo.js", "bar": "./bar.js" }, } Dicts of bins not additive. The most specific match wins. In the future, this field may be automatically populated from information in the pnpm lock file. That feature is currently blocked on pnpm/pnpm#5131. Note: Bzlmod users must use an alternative syntax due to module extensions not supporting dict-of-dict attributes: bins = { "@foo/bar": [ "foo=./foo.js", "bar=./bar.js" ], }	{}
verify_node_modules_ignored	node_modules folders in the source tree should be ignored by Bazel. This points to a .bazelignore file to verify that all nested node_modules directories pnpm will create are listed. See bazelbuild/bazel#8106	None
verify_patches	Label to a patch list file. Use this in together with the list_patches macro to guarantee that all patches in a patch folder are included in the patches attribute. For example: verify_patches = "//patches:patches.list", In your patches folder add a BUILD.bazel file containing. load("@aspect_rules_js//npm:repositories.bzl", "list_patches") list_patches( name = "patches", out = "patches.list", ) Once you have created this file, you need to create an empty patches.list file before generating the first list. You can do this by running touch patches/patches.list Finally, write the patches file at least once to make sure all patches are listed. This can be done by running bazel run //patches:patches_update. See the list_patches documentation for further info. NOTE: if you would like to customize the patches directory location, you can set a flag in the .npmrc. Here is an example of what this might look like # Set the directory for pnpm when patching # https://github.com/pnpm/pnpm/issues/6508#issuecomment-1537242124&#10;patches-dir=bazel/js/patches If you do this, you will have to update the verify_patches path to be this path instead of //patches like above.	None
quiet	Set to False to print info logs and output stdout & stderr of pnpm lock update actions to the console.	True
external_repository_action_cache	The location of the external repository action cache to write to when update_pnpm_lock = True.	".aspect/rules/external_repository_action_cache"
link_workspace	The workspace name where links will be created for the packages in this lock file. This is typically set in rule sets and libraries that vendor the starlark generated by npm_translate_lock so the link_workspace passed to npm_import is set correctly so that links are created in the external repository and not the user workspace. Can be left unspecified if the link workspace is the user workspace.	None
pnpm_version	pnpm version to use when generating the @pnpm repository. Set to None to not create this repository. Can be left unspecified and the rules_js default DEFAULT_PNPM_VERSION will be used.	"8.15.9"
use_pnpm	label of the pnpm entry point to use.	None
npm_package_target_name	The name of linked npm_package, js_library or JsInfo producing targets. When targets are linked as pnpm workspace packages, the name of the target must align with this value. The {dirname} placeholder is replaced with the directory name of the target.	"pkg"
kwargs	Internal use only	none