From b688a5205170710f1ee60b05e1c5443920e4d7dd Mon Sep 17 00:00:00 2001 From: Derek Cormier Date: Wed, 18 Oct 2023 12:14:16 -0700 Subject: [PATCH] docs: document bins attr for bzlmod --- docs/npm_translate_lock.md | 2 +- npm/private/npm_translate_lock.bzl | 12 ++++++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/npm_translate_lock.md b/docs/npm_translate_lock.md index 8a2f82e3f..21b191b21 100644 --- a/docs/npm_translate_lock.md +++ b/docs/npm_translate_lock.md @@ -120,7 +120,7 @@ For more about how to use npm_translate_lock, read [pnpm and rules_js](/docs/pnp | lifecycle_hooks_exclude | A list of package names or package names with their version (e.g., "my-package" or "my-package@v1.2.3") to not run any lifecycle hooks on.

Equivalent to adding <value>: [] to lifecycle_hooks.

Read more: [lifecycles](/docs/pnpm.md#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](/docs/pnpm.md#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](/docs/pnpm.md#lifecycles) | True | -| 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 https://github.com/pnpm/pnpm/issues/5131. | {} | +| 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 https://github.com/pnpm/pnpm/issues/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 https://github.com/bazelbuild/bazel/issues/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 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 | diff --git a/npm/private/npm_translate_lock.bzl b/npm/private/npm_translate_lock.bzl index a69b39afb..1824af706 100644 --- a/npm/private/npm_translate_lock.bzl +++ b/npm/private/npm_translate_lock.bzl @@ -386,6 +386,18 @@ def npm_translate_lock( In the future, this field may be automatically populated from information in the pnpm lock file. That feature is currently blocked on https://github.com/pnpm/pnpm/issues/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