Skip to content

Commit 77dbcfc

Browse files
RafaelGSSwraithgar
authored andcommitted
doc: add section about using npx with permission model
Co-Authored-By: Gar <gar+gh@danger.computer> Signed-off-by: RafaelGSS <rafael.nunu@hotmail.com> PR-URL: #56539 Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Ruy Adorno <ruy@vlt.sh> Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
1 parent 73e5140 commit 77dbcfc

File tree

1 file changed

+38
-0
lines changed

1 file changed

+38
-0
lines changed

doc/api/permissions.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -581,6 +581,43 @@ does not exist, the wildcard will not be added, and access will be limited to
581581
yet, make sure to explicitly include the wildcard:
582582
`/my-path/folder-do-not-exist/*`.
583583

584+
#### Using the Permission Model with `npx`
585+
586+
If you're using [`npx`][] to execute a Node.js script, you can enable the
587+
Permission Model by passing the `--node-options` flag. For example:
588+
589+
```bash
590+
npx --node-options="--permission" package-name
591+
```
592+
593+
This sets the `NODE_OPTIONS` environment variable for all Node.js processes
594+
spawned by [`npx`][], without affecting the `npx` process itself.
595+
596+
**FileSystemRead Error with `npx`**
597+
598+
The above command will likely throw a `FileSystemRead` invalid access error
599+
because Node.js requires file system read access to locate and execute the
600+
package. To avoid this:
601+
602+
1. **Using a Globally Installed Package**
603+
Grant read access to the global `node_modules` directory by running:
604+
605+
```bash
606+
npx --node-options="--permission --allow-fs-read=$(npm prefix -g)" package-name
607+
```
608+
609+
2. **Using the `npx` Cache**
610+
If you are installing the package temporarily or relying on the `npx` cache,
611+
grant read access to the npm cache directory:
612+
613+
```bash
614+
npx --node-options="--permission --allow-fs-read=$(npm config get cache)" package-name
615+
```
616+
617+
Any arguments you would normally pass to `node` (e.g., `--allow-*` flags) can
618+
also be passed through the `--node-options` flag. This flexibility makes it
619+
easy to configure permissions as needed when using `npx`.
620+
584621
#### Permission Model constraints
585622

586623
There are constraints you need to know before using this system:
@@ -620,6 +657,7 @@ There are constraints you need to know before using this system:
620657
[`--allow-wasi`]: cli.md#--allow-wasi
621658
[`--allow-worker`]: cli.md#--allow-worker
622659
[`--experimental-permission`]: cli.md#--experimental-permission
660+
[`npx`]: https://docs.npmjs.com/cli/commands/npx
623661
[`permission.has()`]: process.md#processpermissionhasscope-reference
624662
[relative-url string]: https://url.spec.whatwg.org/#relative-url-with-fragment-string
625663
[special schemes]: https://url.spec.whatwg.org/#special-scheme

0 commit comments

Comments
 (0)