Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: add section about using npx with permission model #56539

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions doc/api/permissions.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,43 @@ does not exist, the wildcard will not be added, and access will be limited to
yet, make sure to explicitly include the wildcard:
`/my-path/folder-do-not-exist/*`.

#### Using the Permission Model with `npx`

If you're using [`npx`][] to execute a Node.js script, you can enable the
Permission Model by passing the `--node-options` flag. For example:

```bash
npx --node-options="--permission" package-name
```

This sets the `NODE_OPTIONS` environment variable for all Node.js processes
spawned by [`npx`][], without affecting the `npx` process itself.

**FileSystemRead Error with `npx`**

The above command will likely throw a `FileSystemRead` invalid access error
RafaelGSS marked this conversation as resolved.
Show resolved Hide resolved
because Node.js requires file system read access to locate and execute the
package. To avoid this:

1. **Using a Globally Installed Package**
Grant read access to the global `node_modules` directory by running:

```bash
npx --node-options="--permission --allow-fs-read=$(npm prefix -g)" package-name
```

2. **Using the `npx` Cache**
If you are installing the package temporarily or relying on the `npx` cache,
grant read access to the npm cache directory:

```bash
npx --node-options="--permission --allow-fs-read=$(npm config get cache)" package-name
```

Any arguments you would normally pass to `node` (e.g., `--allow-*` flags) can
also be passed through the `--node-options` flag. This flexibility makes it
easy to configure permissions as needed when using `npx`.

#### Permission Model constraints

There are constraints you need to know before using this system:
Expand Down Expand Up @@ -166,4 +203,5 @@ There are constraints you need to know before using this system:
[`--allow-wasi`]: cli.md#--allow-wasi
[`--allow-worker`]: cli.md#--allow-worker
[`--permission`]: cli.md#--permission
[`npx`]: https://docs.npmjs.com/cli/commands/npx
[`permission.has()`]: process.md#processpermissionhasscope-reference
Loading