@@ -126,6 +126,43 @@ does not exist, the wildcard will not be added, and access will be limited to |
126 | 126 | yet, make sure to explicitly include the wildcard: |
127 | 127 | `/my-path/folder-do-not-exist/*`. |
128 | 128 |
|
| 129 | +#### Using the Permission Model with `npx` |
| 130 | + |
| 131 | +If you're using [`npx`][] to execute a Node.js script, you can enable the |
| 132 | +Permission Model by passing the `--node-options` flag. For example: |
| 133 | + |
| 134 | +```bash |
| 135 | +npx --node-options="--permission" package-name |
| 136 | +``` |
| 137 | + |
| 138 | +This sets the `NODE_OPTIONS` environment variable for all Node.js processes |
| 139 | +spawned by [`npx`][], without affecting the `npx` process itself. |
| 140 | + |
| 141 | +**FileSystemRead Error with `npx`** |
| 142 | + |
| 143 | +The above command will likely throw a `FileSystemRead` invalid access error |
| 144 | +because Node.js requires file system read access to locate and execute the |
| 145 | +package. To avoid this: |
| 146 | + |
| 147 | +1. **Using a Globally Installed Package** |
| 148 | + Grant read access to the global `node_modules` directory by running: |
| 149 | + |
| 150 | + ```bash |
| 151 | + npx --node-options="--permission --allow-fs-read=$(npm prefix -g)" package-name |
| 152 | + ``` |
| 153 | + |
| 154 | +2. **Using the `npx` Cache** |
| 155 | + If you are installing the package temporarily or relying on the `npx` cache, |
| 156 | + grant read access to the npm cache directory: |
| 157 | + |
| 158 | + ```bash |
| 159 | + npx --node-options="--permission --allow-fs-read=$(npm config get cache)" package-name |
| 160 | + ``` |
| 161 | + |
| 162 | +Any arguments you would normally pass to `node` (e.g., `--allow-*` flags) can |
| 163 | +also be passed through the `--node-options` flag. This flexibility makes it |
| 164 | +easy to configure permissions as needed when using `npx`. |
| 165 | + |
129 | 166 | #### Permission Model constraints |
130 | 167 |
|
131 | 168 | There are constraints you need to know before using this system: |
@@ -166,4 +203,5 @@ There are constraints you need to know before using this system: |
166 | 203 | [`--allow-wasi`]: cli.md#--allow-wasi |
167 | 204 | [`--allow-worker`]: cli.md#--allow-worker |
168 | 205 | [`--permission`]: cli.md#--permission |
| 206 | +[`npx`]: https://docs.npmjs.com/cli/commands/npx |
169 | 207 | [`permission.has()`]: process.md#processpermissionhasscope-reference |