docs/faq.md - third_party/github/aspect-build/rules_js - Git at Google

 ---
 title: FAQ
 ---

 ## Flaky build failure: Exec failed due to IOException

 Known issue: we sometimes see

 ```
 (00:55:55) ERROR: /mnt/ephemeral/workdir/BUILD.bazel:46:22: Copying directory aspect_rules_js~1.37.0~npm~npm__picocolors__1.0.0/package failed: Exec failed due to IOException: /mnt/ephemeral/output/__main__/execroot/_main/external/aspect_rules_js~1.37.0~npm~npm__picocolors__1.0.0/package (No such file or directory)
 ```

 This is most likely caused by https://github.com/bazelbuild/bazel/issues/22073. You can either update to Bazel 7.2.0rc1 or later or temporarily add this line to `.bazelrc`:

 ```
 common --noexperimental_merged_skyframe_analysis_execution
 ```

 ## Why does my program fail with "Module not found"?

 See the [Troubleshooting guide](./troubleshooting.md).

 ## Making the editor happy

 Editors (and the language services they host) expect a couple of things:

 -   third-party tooling like the TypeScript SDK under `<project root>/node_modules`
 -   types for your first-party imports

 Since rules_js puts the outputs under Bazel's `bazel-out` tree, the editor doesn't find them by default.

 To get local tooling installed, you can continue to run `pnpm install` (or use whatever package manager your lockfile is for)
 to get a `node_modules` tree in your project.
 If there are many packages to install, you could reduce this by only installing the tooling
 actually needed for non-Bazel workflows, like the `@types/*` packages and `typescript`.

 To resolve first-party imports like `import '@myorg/my_lib'` to resolve in TypeScript, use the
 `paths` key in the `tsconfig.json` file to list additional search locations.
 This is the same thing you'd do outside of Bazel.
 See [example](https://github.com/aspect-build/rules_ts/blob/74d54bda208695d7e8992520e560166875cfbce7/examples/simple/tsconfig.json#L4-L10).

 ## Bazel isn't seeing my changes to package.json

 rules_js relies on what's in the `pnpm-lock.yaml` file. Make sure your changes are reflected there.

 Set `update_pnpm_lock` to True in your `npm_translate_lock` rule and Bazel will auto-update your
 `pnpm-lock.yaml` when any of its inputs change. When you do this, add all files required
 for pnpm to generate the `pnpm-lock.yaml` to the `data` attribute of `npm_translate_lock`. This will
 include the `pnpm-workspace.yaml` if it exists and all `package.json` files in your pnpm workspace.

 To list all local `package.json` files that pnpm needs to read, you can run
 `pnpm recursive ls --depth -1 --porcelain`.

 ## Can a tool run outside of Bazel write to the `node_modules` in `bazel-out`?

 Some tools such as the AWS SDK write to `node_modules` when they are run. Ideally this should be avoided or fixed in an upstream package. Bazel write-protects the files in the `bazel-out` output tree so they can be reliably cached and reused.

 If necessary the `node_modules` directory permissions can be manually modified, however these changes will be detected and overwritten next time Bazel runs. To maintain these edits across Bazel runs, you can use the `--experimental_check_output_files=false` flag.

 ## Can I edit files in `node_modules` for debugging?

 Try running Bazel with `--experimental_check_output_files=false` so that your edits inside the `bazel-out/node_modules` tree are preserved.

 ## Can I use bazel-managed pnpm?

 Yes, just run `bazel run -- @pnpm//:pnpm --dir $PWD` followed by the usual arguments to pnpm.

 If you're bootstrapping a new project, you'll need to add this to your WORKSPACE:

 ```starlark
 load("@aspect_rules_js//npm:repositories.bzl", "pnpm_repository")

 pnpm_repository(name = "pnpm")
 ```

 Or, if you're using [bzlmod](https://bazel.build/external/overview#bzlmod), add these lines to your MODULE.bazel:

 ```starlark
 pnpm = use_extension("@aspect_rules_js//npm:extensions.bzl", "pnpm", dev_dependency = True)

 use_repo(pnpm, "pnpm")
 ```

 This defines the `@pnpm` repository so that you can create the lockfile with
 `bazel run -- @pnpm//:pnpm --dir $PWD install --lockfile-only`, and then once the file exists you'll
 be able to add the `pnpm_translate_lock` to the `WORKSPACE` which requires the lockfile.

 Consider documenting running pnpm through bazel as a good practice for your team, so that all developers run the exact same pnpm and node versions that Bazel does.

 ## Why can't Bazel fetch an npm package?

 If the error looks like this: `failed to fetch. no such package '@npm__foo__1.2.3//': at offset 773, object has duplicate key`
 then you are hitting https://github.com/bazelbuild/bazel/issues/15605

 The workaround is to patch the package.json of any offending packages in npm_translate_lock, see https://github.com/aspect-build/rules_js/issues/148#issuecomment-1144378565.
 Or, if a newer version of the package has fixed the duplicate keys, you could upgrade.

 If the error looks like this: `ERR_PNPM_FETCH_404 GET https://registry.npmjs.org/@my-workspace%2Ffoo: Not Found - 404`, where `foo` is a package living in a workspace in your local
 codebase and it's being declared [`pnpm-workspace.yaml`](https://pnpm.io/pnpm-workspace_yaml) and that you are relying on the `yarn_lock` attribute of `npm_translate_lock`, then
 you're hitting a caveat of the migration process.

 The workaround is to generate the `pnpm-lock.yaml` on your own as mentioned in the migration guide and to use the `pnpm_lock` attribute of `npm_translate_lock` instead.

 ## In my monorepo, can Bazel output multiple packages under one dist/ folder?

 Many projects have a structure like the following:

 ```
 my-workspace/
 ├─ packages/
 │  ├─ lib1/
 │  └─ lib2/
 └─ dist/
    ├─ lib1/
    └─ lib2/
 ```

 However, Bazel has a constraint that outputs for a given Bazel package (a directory containing a `BUILD` file) must be written under the corresponding output folder. This means that you have two choices:

 1. **Keep your output structure the same.** This implies there must be a single `BUILD` file under `my-workspace`, since this is the only Bazel package which can output to paths beneath `my-workspace/dist`. The downside is that this `BUILD` file may get long, accumulate a lot of `load` statements, and the paths inside will be longer.

 The result looks like this:

 ```
 my-workspace/
 ├─ BUILD.bazel
 ├─ packages/
 │  ├─ lib1/
 │  └─ lib2/
 └─ bazel-bin/packages/
    ├─ lib1/
    └─ lib2/
 ```

 2. **Change your output structure** to distribute `dist` folders beneath `lib1` and `lib2`. Now you can have `BUILD` files underneath each library, which is more Bazel-idiomatic.

 The result looks like this:

 ```
 my-workspace/
 ├─ packages/
 │  ├─ lib1/
 │  |  └─ BUILD.bazel
 │  ├─ lib2/
 │  |  └─ BUILD.bazel
 └─ bazel-bin/packages/
    ├─ lib1/
    |  └─ dist/
    └─ lib2/
       └─ dist/
 ```

 Note that when following option 2, it might require updating some configuration files which refer to the original output locations. For example, your `tsconfig.json` file might have a `paths` section which points to the `../../dist` folder.

 To keep your legacy build system working during the migration, you might want to avoid changing those configuration files in-place. For this purpose, you can use [the `jq` rule](https://github.com/bazel-contrib/bazel-lib/blob/main/docs/jq.md) in place of `copy_to_bin`, using a `filter` expression so the copy of the configuration file in `bazel-bin` that's used by the Bazel build can have a different path than the configuration file in the source tree.
	---
	title: FAQ
	---

	## Flaky build failure: Exec failed due to IOException

	Known issue: we sometimes see

	```
	(00:55:55) ERROR: /mnt/ephemeral/workdir/BUILD.bazel:46:22: Copying directory aspect_rules_js~1.37.0~npm~npm__picocolors__1.0.0/package failed: Exec failed due to IOException: /mnt/ephemeral/output/__main__/execroot/_main/external/aspect_rules_js~1.37.0~npm~npm__picocolors__1.0.0/package (No such file or directory)
	```

	This is most likely caused by https://github.com/bazelbuild/bazel/issues/22073. You can either update to Bazel 7.2.0rc1 or later or temporarily add this line to `.bazelrc`:

	```
	common --noexperimental_merged_skyframe_analysis_execution
	```

	## Why does my program fail with "Module not found"?

	See the [Troubleshooting guide](./troubleshooting.md).

	## Making the editor happy

	Editors (and the language services they host) expect a couple of things:

	- third-party tooling like the TypeScript SDK under `<project root>/node_modules`
	- types for your first-party imports

	Since rules_js puts the outputs under Bazel's `bazel-out` tree, the editor doesn't find them by default.

	To get local tooling installed, you can continue to run `pnpm install` (or use whatever package manager your lockfile is for)
	to get a `node_modules` tree in your project.
	If there are many packages to install, you could reduce this by only installing the tooling
	actually needed for non-Bazel workflows, like the `@types/*` packages and `typescript`.

	To resolve first-party imports like `import '@myorg/my_lib'` to resolve in TypeScript, use the
	`paths` key in the `tsconfig.json` file to list additional search locations.
	This is the same thing you'd do outside of Bazel.
	See [example](https://github.com/aspect-build/rules_ts/blob/74d54bda208695d7e8992520e560166875cfbce7/examples/simple/tsconfig.json#L4-L10).

	## Bazel isn't seeing my changes to package.json

	rules_js relies on what's in the `pnpm-lock.yaml` file. Make sure your changes are reflected there.

	Set `update_pnpm_lock` to True in your `npm_translate_lock` rule and Bazel will auto-update your
	`pnpm-lock.yaml` when any of its inputs change. When you do this, add all files required
	for pnpm to generate the `pnpm-lock.yaml` to the `data` attribute of `npm_translate_lock`. This will
	include the `pnpm-workspace.yaml` if it exists and all `package.json` files in your pnpm workspace.

	To list all local `package.json` files that pnpm needs to read, you can run
	`pnpm recursive ls --depth -1 --porcelain`.

	## Can a tool run outside of Bazel write to the `node_modules` in `bazel-out`?

	Some tools such as the AWS SDK write to `node_modules` when they are run. Ideally this should be avoided or fixed in an upstream package. Bazel write-protects the files in the `bazel-out` output tree so they can be reliably cached and reused.

	If necessary the `node_modules` directory permissions can be manually modified, however these changes will be detected and overwritten next time Bazel runs. To maintain these edits across Bazel runs, you can use the `--experimental_check_output_files=false` flag.

	## Can I edit files in `node_modules` for debugging?

	Try running Bazel with `--experimental_check_output_files=false` so that your edits inside the `bazel-out/node_modules` tree are preserved.

	## Can I use bazel-managed pnpm?

	Yes, just run `bazel run -- @pnpm//:pnpm --dir $PWD` followed by the usual arguments to pnpm.

	If you're bootstrapping a new project, you'll need to add this to your WORKSPACE:

	```starlark
	load("@aspect_rules_js//npm:repositories.bzl", "pnpm_repository")

	pnpm_repository(name = "pnpm")
	```

	Or, if you're using [bzlmod](https://bazel.build/external/overview#bzlmod), add these lines to your MODULE.bazel:

	```starlark
	pnpm = use_extension("@aspect_rules_js//npm:extensions.bzl", "pnpm", dev_dependency = True)

	use_repo(pnpm, "pnpm")
	```

	This defines the `@pnpm` repository so that you can create the lockfile with
	`bazel run -- @pnpm//:pnpm --dir $PWD install --lockfile-only`, and then once the file exists you'll
	be able to add the `pnpm_translate_lock` to the `WORKSPACE` which requires the lockfile.

	Consider documenting running pnpm through bazel as a good practice for your team, so that all developers run the exact same pnpm and node versions that Bazel does.

	## Why can't Bazel fetch an npm package?

	If the error looks like this: `failed to fetch. no such package '@npm__foo__1.2.3//': at offset 773, object has duplicate key`
	then you are hitting https://github.com/bazelbuild/bazel/issues/15605

	The workaround is to patch the package.json of any offending packages in npm_translate_lock, see https://github.com/aspect-build/rules_js/issues/148#issuecomment-1144378565.
	Or, if a newer version of the package has fixed the duplicate keys, you could upgrade.

	If the error looks like this: `ERR_PNPM_FETCH_404 GET https://registry.npmjs.org/@my-workspace%2Ffoo: Not Found - 404`, where `foo` is a package living in a workspace in your local
	codebase and it's being declared [`pnpm-workspace.yaml`](https://pnpm.io/pnpm-workspace_yaml) and that you are relying on the `yarn_lock` attribute of `npm_translate_lock`, then
	you're hitting a caveat of the migration process.

	The workaround is to generate the `pnpm-lock.yaml` on your own as mentioned in the migration guide and to use the `pnpm_lock` attribute of `npm_translate_lock` instead.

	## In my monorepo, can Bazel output multiple packages under one dist/ folder?

	Many projects have a structure like the following:

	```
	my-workspace/
	├─ packages/
	│ ├─ lib1/
	│ └─ lib2/
	└─ dist/
	├─ lib1/
	└─ lib2/
	```

	However, Bazel has a constraint that outputs for a given Bazel package (a directory containing a `BUILD` file) must be written under the corresponding output folder. This means that you have two choices:

	1. Keep your output structure the same. This implies there must be a single `BUILD` file under `my-workspace`, since this is the only Bazel package which can output to paths beneath `my-workspace/dist`. The downside is that this `BUILD` file may get long, accumulate a lot of `load` statements, and the paths inside will be longer.

	The result looks like this:

	```
	my-workspace/
	├─ BUILD.bazel
	├─ packages/
	│ ├─ lib1/
	│ └─ lib2/
	└─ bazel-bin/packages/
	├─ lib1/
	└─ lib2/
	```

	2. Change your output structure to distribute `dist` folders beneath `lib1` and `lib2`. Now you can have `BUILD` files underneath each library, which is more Bazel-idiomatic.

	The result looks like this:

	```
	my-workspace/
	├─ packages/
	│ ├─ lib1/
	│ \| └─ BUILD.bazel
	│ ├─ lib2/
	│ \| └─ BUILD.bazel
	└─ bazel-bin/packages/
	├─ lib1/
	\| └─ dist/
	└─ lib2/
	└─ dist/
	```

	Note that when following option 2, it might require updating some configuration files which refer to the original output locations. For example, your `tsconfig.json` file might have a `paths` section which points to the `../../dist` folder.

	To keep your legacy build system working during the migration, you might want to avoid changing those configuration files in-place. For this purpose, you can use [the `jq` rule](https://github.com/bazel-contrib/bazel-lib/blob/main/docs/jq.md) in place of `copy_to_bin`, using a `filter` expression so the copy of the configuration file in `bazel-bin` that's used by the Bazel build can have a different path than the configuration file in the source tree.