469 lines
13 KiB
Groff
469 lines
13 KiB
Groff
.TH "NPM\-EXEC" "1" "February 2022" "" ""
|
|
.SH "NAME"
|
|
\fBnpm-exec\fR \- Run a command from a local or remote npm package
|
|
.SS Synopsis
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
npm exec \-\- <pkg>[@<version>] [args\.\.\.]
|
|
npm exec \-\-package=<pkg>[@<version>] \-\- <cmd> [args\.\.\.]
|
|
npm exec \-c '<cmd> [args\.\.\.]'
|
|
npm exec \-\-package=foo \-c '<cmd> [args\.\.\.]'
|
|
npm exec [\-\-ws] [\-w <workspace\-name] [args\.\.\.]
|
|
|
|
npx <pkg>[@<specifier>] [args\.\.\.]
|
|
npx \-p <pkg>[@<specifier>] <cmd> [args\.\.\.]
|
|
npx \-c '<cmd> [args\.\.\.]'
|
|
npx \-p <pkg>[@<specifier>] \-c '<cmd> [args\.\.\.]'
|
|
Run without \-\-call or positional args to open interactive subshell
|
|
|
|
alias: npm x, npx
|
|
|
|
common options:
|
|
\-\-package=<pkg> (may be specified multiple times)
|
|
\-p is a shorthand for \-\-package only when using npx executable
|
|
\-c <cmd> \-\-call=<cmd> (may not be mixed with positional arguments)
|
|
.fi
|
|
.RE
|
|
.SS Description
|
|
.P
|
|
This command allows you to run an arbitrary command from an npm package
|
|
(either one installed locally, or fetched remotely), in a similar context
|
|
as running it via \fBnpm run\fP\|\.
|
|
.P
|
|
Run without positional arguments or \fB\-\-call\fP, this allows you to
|
|
interactively run commands in the same sort of shell environment that
|
|
\fBpackage\.json\fP scripts are run\. Interactive mode is not supported in CI
|
|
environments when standard input is a TTY, to prevent hangs\.
|
|
.P
|
|
Whatever packages are specified by the \fB\-\-package\fP option will be
|
|
provided in the \fBPATH\fP of the executed command, along with any locally
|
|
installed package executables\. The \fB\-\-package\fP option may be
|
|
specified multiple times, to execute the supplied command in an environment
|
|
where all specified packages are available\.
|
|
.P
|
|
If any requested packages are not present in the local project
|
|
dependencies, then they are installed to a folder in the npm cache, which
|
|
is added to the \fBPATH\fP environment variable in the executed process\. A
|
|
prompt is printed (which can be suppressed by providing either \fB\-\-yes\fP or
|
|
\fB\-\-no\fP)\.
|
|
.P
|
|
Package names provided without a specifier will be matched with whatever
|
|
version exists in the local project\. Package names with a specifier will
|
|
only be considered a match if they have the exact same name and version as
|
|
the local dependency\.
|
|
.P
|
|
If no \fB\-c\fP or \fB\-\-call\fP option is provided, then the positional arguments
|
|
are used to generate the command string\. If no \fB\-\-package\fP options
|
|
are provided, then npm will attempt to determine the executable name from
|
|
the package specifier provided as the first positional argument according
|
|
to the following heuristic:
|
|
.RS 0
|
|
.IP \(bu 2
|
|
If the package has a single entry in its \fBbin\fP field in \fBpackage\.json\fP,
|
|
or if all entries are aliases of the same command, then that command
|
|
will be used\.
|
|
.IP \(bu 2
|
|
If the package has multiple \fBbin\fP entries, and one of them matches the
|
|
unscoped portion of the \fBname\fP field, then that command will be used\.
|
|
.IP \(bu 2
|
|
If this does not result in exactly one option (either because there are
|
|
no bin entries, or none of them match the \fBname\fP of the package), then
|
|
\fBnpm exec\fP exits with an error\.
|
|
|
|
.RE
|
|
.P
|
|
To run a binary \fIother than\fR the named binary, specify one or more
|
|
\fB\-\-package\fP options, which will prevent npm from inferring the package from
|
|
the first command argument\.
|
|
.SS \fBnpx\fP vs \fBnpm exec\fP
|
|
.P
|
|
When run via the \fBnpx\fP binary, all flags and options \fImust\fR be set prior to
|
|
any positional arguments\. When run via \fBnpm exec\fP, a double\-hyphen \fB\-\-\fP
|
|
flag can be used to suppress npm's parsing of switches and options that
|
|
should be sent to the executed command\.
|
|
.P
|
|
For example:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
$ npx foo@latest bar \-\-package=@npmcli/foo
|
|
.fi
|
|
.RE
|
|
.P
|
|
In this case, npm will resolve the \fBfoo\fP package name, and run the
|
|
following command:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
$ foo bar \-\-package=@npmcli/foo
|
|
.fi
|
|
.RE
|
|
.P
|
|
Since the \fB\-\-package\fP option comes \fIafter\fR the positional arguments, it is
|
|
treated as an argument to the executed command\.
|
|
.P
|
|
In contrast, due to npm's argument parsing logic, running this command is
|
|
different:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
$ npm exec foo@latest bar \-\-package=@npmcli/foo
|
|
.fi
|
|
.RE
|
|
.P
|
|
In this case, npm will parse the \fB\-\-package\fP option first, resolving the
|
|
\fB@npmcli/foo\fP package\. Then, it will execute the following command in that
|
|
context:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
$ foo@latest bar
|
|
.fi
|
|
.RE
|
|
.P
|
|
The double\-hyphen character is recommended to explicitly tell npm to stop
|
|
parsing command line options and switches\. The following command would
|
|
thus be equivalent to the \fBnpx\fP command above:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
$ npm exec \-\- foo@latest bar \-\-package=@npmcli/foo
|
|
.fi
|
|
.RE
|
|
.SS Configuration
|
|
<!\-\- AUTOGENERATED CONFIG DESCRIPTIONS START \-\->
|
|
<!\-\- automatically generated, do not edit manually \-\->
|
|
<!\-\- see lib/utils/config/definitions\.js \-\->
|
|
.SS \fBpackage\fP
|
|
.RS 0
|
|
.IP \(bu 2
|
|
Default:
|
|
.IP \(bu 2
|
|
Type: String (can be set multiple times)
|
|
|
|
.RE
|
|
.P
|
|
The package to install for npm help \fBexec\fP
|
|
<!\-\- automatically generated, do not edit manually \-\->
|
|
<!\-\- see lib/utils/config/definitions\.js \-\->
|
|
|
|
.SS \fBcall\fP
|
|
.RS 0
|
|
.IP \(bu 2
|
|
Default: ""
|
|
.IP \(bu 2
|
|
Type: String
|
|
|
|
.RE
|
|
.P
|
|
Optional companion option for \fBnpm exec\fP, \fBnpx\fP that allows for specifying a
|
|
custom command to be run along with the installed packages\.
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
npm exec \-\-package yo \-\-package generator\-node \-\-call "yo node"
|
|
.fi
|
|
.RE
|
|
<!\-\- automatically generated, do not edit manually \-\->
|
|
<!\-\- see lib/utils/config/definitions\.js \-\->
|
|
|
|
.SS \fBworkspace\fP
|
|
.RS 0
|
|
.IP \(bu 2
|
|
Default:
|
|
.IP \(bu 2
|
|
Type: String (can be set multiple times)
|
|
|
|
.RE
|
|
.P
|
|
Enable running a command in the context of the configured workspaces of the
|
|
current project while filtering by running only the workspaces defined by
|
|
this configuration option\.
|
|
.P
|
|
Valid values for the \fBworkspace\fP config are either:
|
|
.RS 0
|
|
.IP \(bu 2
|
|
Workspace names
|
|
.IP \(bu 2
|
|
Path to a workspace directory
|
|
.IP \(bu 2
|
|
Path to a parent workspace directory (will result in selecting all
|
|
workspaces within that folder)
|
|
|
|
.RE
|
|
.P
|
|
When set for the \fBnpm init\fP command, this may be set to the folder of a
|
|
workspace which does not yet exist, to create the folder and set it up as a
|
|
brand new workspace within the project\.
|
|
.P
|
|
This value is not exported to the environment for child processes\.
|
|
<!\-\- automatically generated, do not edit manually \-\->
|
|
<!\-\- see lib/utils/config/definitions\.js \-\->
|
|
|
|
.SS \fBworkspaces\fP
|
|
.RS 0
|
|
.IP \(bu 2
|
|
Default: null
|
|
.IP \(bu 2
|
|
Type: null or Boolean
|
|
|
|
.RE
|
|
.P
|
|
Set to true to run the command in the context of \fBall\fR configured
|
|
workspaces\.
|
|
.P
|
|
Explicitly setting this to false will cause commands like \fBinstall\fP to
|
|
ignore workspaces altogether\. When not set explicitly:
|
|
.RS 0
|
|
.IP \(bu 2
|
|
Commands that operate on the \fBnode_modules\fP tree (install, update, etc\.)
|
|
will link workspaces into the \fBnode_modules\fP folder\. \- Commands that do
|
|
other things (test, exec, publish, etc\.) will operate on the root project,
|
|
\fIunless\fR one or more workspaces are specified in the \fBworkspace\fP config\.
|
|
|
|
.RE
|
|
.P
|
|
This value is not exported to the environment for child processes\.
|
|
<!\-\- automatically generated, do not edit manually \-\->
|
|
<!\-\- see lib/utils/config/definitions\.js \-\->
|
|
|
|
.SS \fBinclude\-workspace\-root\fP
|
|
.RS 0
|
|
.IP \(bu 2
|
|
Default: false
|
|
.IP \(bu 2
|
|
Type: Boolean
|
|
|
|
.RE
|
|
.P
|
|
Include the workspace root when workspaces are enabled for a command\.
|
|
.P
|
|
When false, specifying individual workspaces via the \fBworkspace\fP config, or
|
|
all workspaces via the \fBworkspaces\fP flag, will cause npm to operate only on
|
|
the specified workspaces, and not on the root project\.
|
|
<!\-\- automatically generated, do not edit manually \-\->
|
|
<!\-\- see lib/utils/config/definitions\.js \-\->
|
|
|
|
<!\-\- AUTOGENERATED CONFIG DESCRIPTIONS END \-\->
|
|
|
|
.SS Examples
|
|
.P
|
|
Run the version of \fBtap\fP in the local dependencies, with the provided
|
|
arguments:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
$ npm exec \-\- tap \-\-bail test/foo\.js
|
|
$ npx tap \-\-bail test/foo\.js
|
|
.fi
|
|
.RE
|
|
.P
|
|
Run a command \fIother than\fR the command whose name matches the package name
|
|
by specifying a \fB\-\-package\fP option:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
$ npm exec \-\-package=foo \-\- bar \-\-bar\-argument
|
|
# ~ or ~
|
|
$ npx \-\-package=foo bar \-\-bar\-argument
|
|
.fi
|
|
.RE
|
|
.P
|
|
Run an arbitrary shell script, in the context of the current project:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
$ npm x \-c 'eslint && say "hooray, lint passed"'
|
|
$ npx \-c 'eslint && say "hooray, lint passed"'
|
|
.fi
|
|
.RE
|
|
.SS Workspaces support
|
|
.P
|
|
You may use the \fBworkspace\fP or \fBworkspaces\fP configs in order to run an
|
|
arbitrary command from an npm package (either one installed locally, or fetched
|
|
remotely) in the context of the specified workspaces\.
|
|
If no positional argument or \fB\-\-call\fP option is provided, it will open an
|
|
interactive subshell in the context of each of these configured workspaces one
|
|
at a time\.
|
|
.P
|
|
Given a project with configured workspaces, e\.g:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
\|\.
|
|
+\-\- package\.json
|
|
`\-\- packages
|
|
+\-\- a
|
|
| `\-\- package\.json
|
|
+\-\- b
|
|
| `\-\- package\.json
|
|
`\-\- c
|
|
`\-\- package\.json
|
|
.fi
|
|
.RE
|
|
.P
|
|
Assuming the workspace configuration is properly set up at the root level
|
|
\fBpackage\.json\fP file\. e\.g:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
{
|
|
"workspaces": [ "\./packages/*" ]
|
|
}
|
|
.fi
|
|
.RE
|
|
.P
|
|
You can execute an arbitrary command from a package in the context of each of
|
|
the configured workspaces when using the \fBworkspaces\fP configuration options,
|
|
in this example we're using \fBeslint\fR to lint any js file found within each
|
|
workspace folder:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
npm exec \-\-ws \-\- eslint \./*\.js
|
|
.fi
|
|
.RE
|
|
.SS Filtering workspaces
|
|
.P
|
|
It's also possible to execute a command in a single workspace using the
|
|
\fBworkspace\fP config along with a name or directory path:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
npm exec \-\-workspace=a \-\- eslint \./*\.js
|
|
.fi
|
|
.RE
|
|
.P
|
|
The \fBworkspace\fP config can also be specified multiple times in order to run a
|
|
specific script in the context of multiple workspaces\. When defining values for
|
|
the \fBworkspace\fP config in the command line, it also possible to use \fB\-w\fP as a
|
|
shorthand, e\.g:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
npm exec \-w a \-w b \-\- eslint \./*\.js
|
|
.fi
|
|
.RE
|
|
.P
|
|
This last command will run the \fBeslint\fP command in both \fB\|\./packages/a\fP and
|
|
\fB\|\./packages/b\fP folders\.
|
|
.SS Compatibility with Older npx Versions
|
|
.P
|
|
The \fBnpx\fP binary was rewritten in npm v7\.0\.0, and the standalone \fBnpx\fP
|
|
package deprecated at that time\. \fBnpx\fP uses the \fBnpm exec\fP
|
|
command instead of a separate argument parser and install process, with
|
|
some affordances to maintain backwards compatibility with the arguments it
|
|
accepted in previous versions\.
|
|
.P
|
|
This resulted in some shifts in its functionality:
|
|
.RS 0
|
|
.IP \(bu 2
|
|
Any \fBnpm\fP config value may be provided\.
|
|
.IP \(bu 2
|
|
To prevent security and user\-experience problems from mistyping package
|
|
names, \fBnpx\fP prompts before installing anything\. Suppress this
|
|
prompt with the \fB\-y\fP or \fB\-\-yes\fP option\.
|
|
.IP \(bu 2
|
|
The \fB\-\-no\-install\fP option is deprecated, and will be converted to \fB\-\-no\fP\|\.
|
|
.IP \(bu 2
|
|
Shell fallback functionality is removed, as it is not advisable\.
|
|
.IP \(bu 2
|
|
The \fB\-p\fP argument is a shorthand for \fB\-\-parseable\fP in npm, but shorthand
|
|
for \fB\-\-package\fP in npx\. This is maintained, but only for the \fBnpx\fP
|
|
executable\.
|
|
.IP \(bu 2
|
|
The \fB\-\-ignore\-existing\fP option is removed\. Locally installed bins are
|
|
always present in the executed process \fBPATH\fP\|\.
|
|
.IP \(bu 2
|
|
The \fB\-\-npm\fP option is removed\. \fBnpx\fP will always use the \fBnpm\fP it ships
|
|
with\.
|
|
.IP \(bu 2
|
|
The \fB\-\-node\-arg\fP and \fB\-n\fP options are removed\.
|
|
.IP \(bu 2
|
|
The \fB\-\-always\-spawn\fP option is redundant, and thus removed\.
|
|
.IP \(bu 2
|
|
The \fB\-\-shell\fP option is replaced with \fB\-\-script\-shell\fP, but maintained
|
|
in the \fBnpx\fP executable for backwards compatibility\.
|
|
|
|
.RE
|
|
.SS A note on caching
|
|
.P
|
|
The npm cli utilizes its internal package cache when using the package
|
|
name specified\. You can use the following to change how and when the
|
|
cli uses this cache\. See npm help \fBcache\fP for more on
|
|
how the cache works\.
|
|
.SS prefer\-online
|
|
.P
|
|
Forces staleness checks for packages, making the cli look for updates
|
|
immediately even if the package is already in the cache\.
|
|
.SS prefer\-offline
|
|
.P
|
|
Bypasses staleness checks for packages\. Missing data will still be
|
|
requested from the server\. To force full offline mode, use \fBoffline\fP\|\.
|
|
.SS offline
|
|
.P
|
|
Forces full offline mode\. Any packages not locally cached will result in
|
|
an error\.
|
|
.SS workspace
|
|
.RS 0
|
|
.IP \(bu 2
|
|
Default:
|
|
.IP \(bu 2
|
|
Type: String (can be set multiple times)
|
|
|
|
.RE
|
|
.P
|
|
Enable running a command in the context of the configured workspaces of the
|
|
current project while filtering by running only the workspaces defined by
|
|
this configuration option\.
|
|
.P
|
|
Valid values for the \fBworkspace\fP config are either:
|
|
.RS 0
|
|
.IP \(bu 2
|
|
Workspace names
|
|
.IP \(bu 2
|
|
Path to a workspace directory
|
|
.IP \(bu 2
|
|
Path to a parent workspace directory (will result to selecting all of the
|
|
nested workspaces)
|
|
|
|
.RE
|
|
.P
|
|
This value is not exported to the environment for child processes\.
|
|
.SS workspaces
|
|
.RS 0
|
|
.IP \(bu 2
|
|
Alias: \fB\-\-ws\fP
|
|
.IP \(bu 2
|
|
Type: Boolean
|
|
.IP \(bu 2
|
|
Default: \fBfalse\fP
|
|
|
|
.RE
|
|
.P
|
|
Run scripts in the context of all configured workspaces for the current
|
|
project\.
|
|
.SS See Also
|
|
.RS 0
|
|
.IP \(bu 2
|
|
npm help run\-script
|
|
.IP \(bu 2
|
|
npm help scripts
|
|
.IP \(bu 2
|
|
npm help test
|
|
.IP \(bu 2
|
|
npm help start
|
|
.IP \(bu 2
|
|
npm help restart
|
|
.IP \(bu 2
|
|
npm help stop
|
|
.IP \(bu 2
|
|
npm help config
|
|
.IP \(bu 2
|
|
npm help workspaces
|
|
.IP \(bu 2
|
|
npm help npx
|
|
|
|
.RE
|