The npx command has been added to npm since version 5.2. It has many uses, and this article introduces the main usage scenarios of the command.

Node comes with an npm module, so you can use the npx command directly. In case it doesn’t work, you’ll have to install it manually.

1
$ npm install -g npx

Calling the project’s installed modules

The main problem that npx is trying to solve is calling modules that are installed inside the project. For example, the project has the testing tool Mocha installed internally.

1
$ npm install -D mocha

In general, Mocha can only be called from the project script and the scripts field of package.json, but if you want to call it from the command line, you have to do something like this.

1
2
# The project's root directory executes
$ node-modules/.bin/mocha --version

npx is trying to solve this problem by making it easier to use the modules installed inside the project, just by calling them like the following

1
$ npx mocha --version

The principle of npx is simple: when running, it will go to the node_modules/.bin path and the environment variable $PATH and check if the command exists.

Since npx checks the environment variable $PATH, system commands can also be called.

1
2
# Equivalent to ls
$ npx ls

Note that Bash built-in commands are not in $PATH, so they cannot be used. For example, cd is a Bash command, so you can’t use npx cd.

Avoid global installation of modules

In addition to calling internal project modules, npx can also avoid globally installed modules. For example, the module create-react-app is a global install and npx can run it and not do a global install.

1
$ npx create-react-app my-react-app

When the above code is run, npx downloads create-react-app to a temporary directory, which will be deleted after use. So, running the above command again later will download create-react-app again.

When downloading global modules, npx allows to specify the version.

1
$ npx uglify-js@3.1.0 main.js -o ./dist/main.js

The above code specifies the use of version 3.1.0 of the uglify-js compression script.

Note that the module with the same name will be downloaded whenever the module after npx cannot be found locally. For example, if the http-server module is not installed locally, the following command will automatically download the module and start a web service in the current directory.

1
$ npx http-server

–no-install and –ignore-existing parameters

If you want npx to force the local module and not download the remote module, you can use the -no-install parameter. If the module does not exist locally, an error will be reported.

1
$ npx --no-install http-server

Conversely, if you ignore the local module with the same name and force the remote module to be installed, you can use the --ignore-existing parameter. For example, if you already have create-react-app globally installed locally, but still want to use the remote module, use this parameter.

1
$ npx --ignore-existing create-react-app my-react-app

Using different versions of node

Using the fact that npx can download modules, you can specify a particular version of Node to run scripts. The trick is to use the node modules from npm.

1
$ npx --ignore-existing create-react-app my-react-app
1
2
$ npx node@0.12.8 -v
v0.12.8

The above command will execute the script using the 0.12.8 version of Node. The idea is to download this version of node from npm, use it, and then delete it.

In some cases, this method is more convenient for switching Node versions than a version manager like nvm.

-p parameter

The -p parameter is used to specify the modules to be installed by npx, so the command in the previous section could be written as follows.

1
2
$ npx -p node@0.12.8 node -v 
v0.12.8

The above command first specifies the installation of node@0.12.8 and then executes the node -v command.

The -p parameter is useful for scenarios where multiple modules need to be installed.

1
$ npx -p lolcatjs -p cowsay [command]

-c parameter

If npx installs multiple modules, by default, only the first executable will use the module installed by npx, while later executables will be interpreted by the shell.

1
2
$ npx -p lolcatjs -p cowsay 'cowsay hello | lolcatjs'
# Throwing Exceptions

In the above code, cowsay hello | lolcatjs will report an error when executed because the first cowsay is interpreted by npx, while the second command localcatjs is interpreted by Shell, but lolcatjs is not globally installed, so it reports an error.

The -c parameter allows all commands to be interpreted by npx. With it, the following code can be executed properly.

1
$ npx -p lolcatjs -p cowsay -c 'cowsay hello | lolcatjs'

Another function of the -c parameter is to bring environment variables to the command you want to execute. As an example, npm provides some environment variables for the current project, which can be viewed with the following command.

1
$ npm run env | grep npm_

The -c parameter brings these npm environment variables into the npx command.

1
$ npx -c 'echo "$npm_package_name"'

The above code will output the project name of the current project.

Running GitHub source code

npx can also execute the source code of modules on GitHub.

1
2
3
4
5
# Execute the Gist code
$ npx https://gist.github.com/zkat/4bc19503fe9e9309e2bfaa2c58074d32

# Execute the repository code
$ npx github:piuccio/cowsay hello

Note that the remote code must be a module, i.e. it must contain package.json and the entry script.


Reference https://www.ruanyifeng.com/blog/2019/02/npx.html