Skip to content

Commit 5473bbd

Browse files
isaacsruyadorno
isaacs
authored and
ruyadorno
committed
Add 'npm exec', port npx to use it directly
This removes libnpx, and adds a new command, 'npm exec', which implements the functionality. As of this change going live, we are dropping support for the standalone top-level package 'npx'. Not all of the functionality of the old version of npx is maintained. The shell fallback functionality is dropped. It's insecure, and not something we want to support or encourage. If anyone wants it, they can hack up their .bashrc file themselves. --no-install is not supported. If the package is not found locally, it is installed in a predictable location in the cache, rather than failing. This is something we might want to review, as automatically installing in the case of misspellings may be a security footgun. --ignore-existing is dropped. Existing packages are always given priority. --quiet or -q can be accomplished by using the --silent npm option, so it's also dropped. --npm option is dropped. npx will always use the npm that it ships with. --node-arg is dropped. There are other ways to set node options via environment variables in the Node.js versions we support. --always-spawn is dropped. npx will always spawn a child process to execute commands. The --shell option can be accomplished by using the --script-shell npm option. --version and --help are just passed through to npm. As an added bonus, I noticed that the files in `bin/` were not getting run. So now we have full coverage for npm-cli.js and npx-cli.js. PR-URL: npm#1588 Credit: @isaacs Close: npm#1588 Reviewed-by: @ruyadorno
1 parent bcc6638 commit 5473bbd

File tree

201 files changed

+1063
-19768
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

201 files changed

+1063
-19768
lines changed

‎.gitignore‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
*.swp
22
npm-debug.log
33
.nyc_output/
4-
/test/bin
54
/test/output.log
65
/test/*/*/node_modules
76
/test/packages/npm-test-depends-on-spark/which-spark.log

‎Makefile‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,7 @@ markdowns = $(shell find docs -name '*.md' | grep -v 'index') README.md
99
cli_mandocs = $(shell find docs/content/cli-commands -name '*.md' \
1010
|sed 's|.md|.1|g' \
1111
|sed 's|docs/content/cli-commands/|man/man1/|g' ) \
12-
man/man1/npm-README.1 \
13-
man/man1/npx.1
12+
man/man1/npm-README.1
1413

1514
files_mandocs = $(shell find docs/content/configuring-npm -name '*.md' \
1615
|sed 's|.md|.5|g' \
@@ -84,9 +83,6 @@ man/man1/%.1: docs/content/cli-commands/%.md scripts/docs-build.js package.json
8483
@[ -d man/man1 ] || mkdir -p man/man1
8584
node scripts/docs-build.js $< $@
8685

87-
man/man1/npx.1: node_modules/libnpx/libnpx.1
88-
cat $< | sed s/libnpx/npx/ > $@
89-
9086
man/man5/npm-json.5: man/man5/package.json.5
9187
cp $< $@
9288

‎bin/npx-cli.js‎

100755100644
Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,30 @@
11
#!/usr/bin/env node
22

3-
const npx = require('libnpx')
4-
const path = require('path')
3+
const cli = require('../lib/cli.js')
54

6-
const NPM_PATH = path.join(__dirname, 'npm-cli.js')
5+
// run the resulting command as `npm exec ...args`
6+
process.argv[1] = require.resolve('./npm-cli.js')
7+
process.argv.splice(2, 0, 'exec')
78

8-
npx(npx.parseArgs(process.argv, NPM_PATH))
9+
// break out of loop when we find a positional argument or --
10+
// If we find a positional arg, we shove -- in front of it, and
11+
// let the normal npm cli handle the rest.
12+
let i
13+
for (i = 3; i < process.argv.length; i++) {
14+
const arg = process.argv[i]
15+
if (arg === '--') {
16+
break
17+
} else if (/^-/.test(arg)) {
18+
// `--package foo` treated the same as `--package=foo`
19+
if (!arg.includes('=')) {
20+
i++
21+
}
22+
continue
23+
} else {
24+
// found a positional arg, put -- in front of it, and we're done
25+
process.argv.splice(i, 0, '--')
26+
break
27+
}
28+
}
29+
30+
cli(process)

‎docs/content/cli-commands/npm-exec.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
section: cli-commands
3+
title: npm-exec
4+
description: Run a command from a local or remote npm package
5+
---
6+
7+
# npm-exec(1)
8+
9+
## Run a command from a local or remote npm package
10+
11+
### Synopsis
12+
13+
```bash
14+
npm exec -- <pkg>[@<version>] [args...]
15+
npm exec -p <pkg>[@<version>] -- <cmd> [args...]
16+
npm exec -c '<cmd> [args...]'
17+
npm exec -p foo -c '<cmd> [args...]'
18+
19+
npx <pkg>[@<specifier>] [args...]
20+
npx -p <pkg>[@<specifier>] <cmd> [args...]
21+
npx -c '<cmd> [args...]'
22+
npx -p <pkg>[@<specifier>] -c '<cmd> [args...]'
23+
24+
alias: npm x, npx
25+
26+
-p <pkg> --package=<pkg> (may be specified multiple times)
27+
-c <cmd> --call=<cmd> (may not be mixed with positional arguments)
28+
```
29+
30+
### Description
31+
32+
This command allows you to run an arbitrary command from an npm package
33+
(either one installed locally, or fetched remotely), in a similar context
34+
as running it via `npm run`.
35+
36+
Whatever packages are specified by the `--package` or `-p` option will be
37+
provided in the `PATH` of the executed command, along with any locally
38+
installed package executables. The `--package` or `-p` option may be
39+
specified multiple times, to execute the supplied command in an environment
40+
where all specified packages are available.
41+
42+
If any requested packages are not present in the local project
43+
dependencies, then they are installed to a folder in the npm cache, which
44+
is added to the `PATH` environment variable in the executed process.
45+
Package names provided without a specifier will be matched with whatever
46+
version exists in the local project. Package names with a specifier will
47+
only be considered a match if they have the exact same name and version as
48+
the local dependency.
49+
50+
If no `-c` or `--call` option is provided, then the positional arguments
51+
are used to generate the command string. If no `-p` or `--package` options
52+
are provided, then npm will attempt to determine the executable name from
53+
the package specifier provided as the first positional argument according
54+
to the following heuristic:
55+
56+
- If the package has a single entry in its `bin` field in `package.json`,
57+
then that command will be used.
58+
- If the package has multiple `bin` entries, and one of them matches the
59+
unscoped portion of the `name` field, then that command will be used.
60+
- If this does not result in exactly one option (either because there are
61+
no bin entries, or none of them match the `name` of the package), then
62+
`npm exec` exits with an error.
63+
64+
To run a binary _other than_ the named binary, specify one or more
65+
`--package` options, which will prevent npm from inferring the package from
66+
the first command argument.
67+
68+
### `npx` vs `npm exec`
69+
70+
When run via the `npx` binary, all flags and options *must* be set prior to
71+
any positional arguments. When run via `npm exec`, a double-hyphen `--`
72+
flag can be used to suppress npm's parsing of switches and options that
73+
should be sent to the executed command.
74+
75+
For example:
76+
77+
```
78+
$ npx foo@latest bar --package=@npmcli/foo
79+
```
80+
81+
In this case, npm will resolve the `foo` package name, and run the
82+
following command:
83+
84+
```
85+
$ foo bar --package=@npmcli/foo
86+
```
87+
88+
Since the `--package` option comes _after_ the positional arguments, it is
89+
treated as an argument to the executed command.
90+
91+
In contrast, due to npm's argument parsing logic, running this command is
92+
different:
93+
94+
```
95+
$ npm exec foo@latest bar --package=@npmcli/foo
96+
```
97+
98+
In this case, npm will parse the `--package` option first, resolving the
99+
`@npmcli/foo` package. Then, it will execute the following command in that
100+
context:
101+
102+
```
103+
$ foo@latest bar
104+
```
105+
106+
The double-hyphen character is recommended to explicitly tell npm to stop
107+
parsing command line options and switches. The following command would
108+
thus be equivalent to the `npx` command above:
109+
110+
```
111+
$ npm exec -- foo@latest bar --package=@npmcli/foo
112+
```
113+
114+
### Examples
115+
116+
Run the version of `tap` in the local dependencies, with the provided
117+
arguments:
118+
119+
```
120+
$ npm exec -- tap --bail test/foo.js
121+
$ npx tap --bail test/foo.js
122+
```
123+
124+
Run a command _other than_ the command whose name matches the package name
125+
by specifying a `--package` option:
126+
127+
```
128+
$ npm exec --package=foo -- bar --bar-argument
129+
# ~ or ~
130+
$ npx --package=foo bar --bar-argument
131+
```
132+
133+
Run an arbitrary shell script, in the context of the current project:
134+
135+
```
136+
$ npm x -c 'eslint && say "hooray, lint passed"'
137+
$ npx -c 'eslint && say "hooray, lint passed"'
138+
```
139+
140+
### See Also
141+
142+
* [npm run-script](/cli-commands/run-script)
143+
* [npm scripts](/using-npm/scripts)
144+
* [npm test](/cli-commands/test)
145+
* [npm start](/cli-commands/start)
146+
* [npm restart](/cli-commands/restart)
147+
* [npm stop](/cli-commands/stop)
148+
* [npm config](/cli-commands/config)

‎docs/content/cli-commands/npx.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
section: cli-commands
3+
title: npx
4+
description: Run a command from a local or remote npm package
5+
---
6+
7+
# npx(1)
8+
9+
## Run a command from a local or remote npm package
10+
11+
### Synopsis
12+
13+
```bash
14+
npm exec -- <pkg>[@<version>] [args...]
15+
npm exec -p <pkg>[@<version>] -- <cmd> [args...]
16+
npm exec -c '<cmd> [args...]'
17+
npm exec -p foo -c '<cmd> [args...]'
18+
19+
npx <pkg>[@<specifier>] [args...]
20+
npx -p <pkg>[@<specifier>] <cmd> [args...]
21+
npx -c '<cmd> [args...]'
22+
npx -p <pkg>[@<specifier>] -c '<cmd> [args...]'
23+
24+
alias: npm x, npx
25+
26+
-p <pkg> --package=<pkg> (may be specified multiple times)
27+
-c <cmd> --call=<cmd> (may not be mixed with positional arguments)
28+
```
29+
30+
### Description
31+
32+
This command allows you to run an arbitrary command from an npm package
33+
(either one installed locally, or fetched remotely), in a similar context
34+
as running it via `npm run`.
35+
36+
Whatever packages are specified by the `--package` or `-p` option will be
37+
provided in the `PATH` of the executed command, along with any locally
38+
installed package executables. The `--package` or `-p` option may be
39+
specified multiple times, to execute the supplied command in an environment
40+
where all specified packages are available.
41+
42+
If any requested packages are not present in the local project
43+
dependencies, then they are installed to a folder in the npm cache, which
44+
is added to the `PATH` environment variable in the executed process.
45+
Package names provided without a specifier will be matched with whatever
46+
version exists in the local project. Package names with a specifier will
47+
only be considered a match if they have the exact same name and version as
48+
the local dependency.
49+
50+
If no `-c` or `--call` option is provided, then the positional arguments
51+
are used to generate the command string. If no `-p` or `--package` options
52+
are provided, then npm will attempt to determine the executable name from
53+
the package specifier provided as the first positional argument according
54+
to the following heuristic:
55+
56+
- If the package has a single entry in its `bin` field in `package.json`,
57+
then that command will be used.
58+
- If the package has multiple `bin` entries, and one of them matches the
59+
unscoped portion of the `name` field, then that command will be used.
60+
- If this does not result in exactly one option (either because there are
61+
no bin entries, or none of them match the `name` of the package), then
62+
`npm exec` exits with an error.
63+
64+
To run a binary _other than_ the named binary, specify one or more
65+
`--package` options, which will prevent npm from inferring the package from
66+
the first command argument.
67+
68+
### `npx` vs `npm exec`
69+
70+
When run via the `npx` binary, all flags and options *must* be set prior to
71+
any positional arguments. When run via `npm exec`, a double-hyphen `--`
72+
flag can be used to suppress npm's parsing of switches and options that
73+
should be sent to the executed command.
74+
75+
For example:
76+
77+
```
78+
$ npx foo@latest bar --package=@npmcli/foo
79+
```
80+
81+
In this case, npm will resolve the `foo` package name, and run the
82+
following command:
83+
84+
```
85+
$ foo bar --package=@npmcli/foo
86+
```
87+
88+
Since the `--package` option comes _after_ the positional arguments, it is
89+
treated as an argument to the executed command.
90+
91+
In contrast, due to npm's argument parsing logic, running this command is
92+
different:
93+
94+
```
95+
$ npm exec foo@latest bar --package=@npmcli/foo
96+
```
97+
98+
In this case, npm will parse the `--package` option first, resolving the
99+
`@npmcli/foo` package. Then, it will execute the following command in that
100+
context:
101+
102+
```
103+
$ foo@latest bar
104+
```
105+
106+
The double-hyphen character is recommended to explicitly tell npm to stop
107+
parsing command line options and switches. The following command would
108+
thus be equivalent to the `npx` command above:
109+
110+
```
111+
$ npm exec -- foo@latest bar --package=@npmcli/foo
112+
```
113+
114+
### Examples
115+
116+
Run the version of `tap` in the local dependencies, with the provided
117+
arguments:
118+
119+
```
120+
$ npm exec -- tap --bail test/foo.js
121+
$ npx tap --bail test/foo.js
122+
```
123+
124+
Run a command _other than_ the command whose name matches the package name
125+
by specifying a `--package` option:
126+
127+
```
128+
$ npm exec --package=foo -- bar --bar-argument
129+
# ~ or ~
130+
$ npx --package=foo bar --bar-argument
131+
```
132+
133+
Run an arbitrary shell script, in the context of the current project:
134+
135+
```
136+
$ npm x -c 'eslint && say "hooray, lint passed"'
137+
$ npx -c 'eslint && say "hooray, lint passed"'
138+
```
139+
140+
### See Also
141+
142+
* [npm run-script](/cli-commands/run-script)
143+
* [npm scripts](/using-npm/scripts)
144+
* [npm test](/cli-commands/test)
145+
* [npm start](/cli-commands/start)
146+
* [npm restart](/cli-commands/restart)
147+
* [npm stop](/cli-commands/stop)
148+
* [npm config](/cli-commands/config)

‎lib/config/cmd-list.js‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ const shorthands = {
1919
v: 'view',
2020
run: 'run-script',
2121
'clean-install': 'ci',
22-
'clean-install-test': 'cit'
22+
'clean-install-test': 'cit',
23+
x: 'exec'
2324
}
2425

2526
const affordances = {
@@ -119,7 +120,8 @@ const cmdList = [
119120
'restart',
120121
'run-script',
121122
'completion',
122-
'doctor'
123+
'doctor',
124+
'exec'
123125
]
124126

125127
const plumbing = ['birthday']

0 commit comments

Comments
 (0)