Execute Packages With npx And npm

The npm package executor (npx) comes in handy to run one-off commands from packages that I want to use but don't need installed, polluting the global namespace.

[#npx-vs-npm]The difference between [.inline-code]npx[.inline-code] and [.inline-code]npm[.inline-code][#npx-vs-npm]

The node package manager ([.inline-code]npm[.inline-code]) allows developers to manage, install, and update packages from the npm registry. On the other hand, [.inline-code]npx[.inline-code] makes it easier for developers to run these packages without having to install them explicitly. These two go hand in hand and [.inline-code]npx[.inline-code] comes pre-bundled with [.inline-code]npm[.inline-code] since version 5.2.0.

With [.inline-code]npx[.inline-code], you do not need to think about if a package has already been installed before running it. If the package does not exist, [.inline-code]npx[.inline-code] will install the package to a folder in the npm cache. 

The key difference between the two is that [.inline-code]npm[.inline-code] requires multiple steps to run packages. You will need to use [.inline-code]npm[.inline-code] to first install the package, and then perform extra steps to execute.

Let's run through an example using the [.inline-code]create-react-app[.inline-code] package, which is a popular package for quickly creating and setting up react projects. The package will create a directory that contains an initial project structure and install the required dependencies to get started with React.

[#executing-a-package-with-npx]Executing a package using [.inline-code]npx[.inline-code][#executing-a-package-with-npx]

The following [.inline-code]npx[.inline-code] command will execute the [.inline-code]create-react-app[.inline-code] package, which will in turn create a new directory called [.inline-code]my-app[.inline-code] in the current directory.

$ npx create-react-app my-app

With this approach, no global installation of the library is needed and the latest version of the package is installed. Assuming that you won't be using [.inline-code]create-react-app[.inline-code] often, using [.inline-code]npx[.inline-code] is a great way to save on disk space and not worry about conflicting versions of the same package.

Using a specific version of a package

If you want to use a specific version of a package instead of the latest, you can specify the version number right after the package name.

For example, if you want to use version [.inline-code]3.0.0[.inline-code] of the [.inline-code]create-react-app[.inline-code] package, you can append it like so:

$ npx create-react-app@3.0.0 my-app

The official npm docs provide many more examples of using the npx flags and options.

[#executing-a-package-with-npm]Executing a package using [.inline-code]npm[.inline-code][#executing-a-package-with-npm]

[#executing-a-global-package]Using a globally installed package[#executing-a-global-package]

To execute a global package with [.inline-code]npm[.inline-code], you can start by installing it globally using the [.inline-code]npm install -g[.inline-code] command:

$ npm install -g create-react-app

And directly execute it using its name:

$ create-react-app my-app

This method is similar to using [.inline-code]npx[.inline-code] with some caveats, as you are now polluting the global space with the package and after some time you will be using an outdated version that may have breaking changes.

[#executing-a-local-package]Using a locally installed package[#executing-a-local-package]

To execute a local package, you can start by installing it in your project using the [.inline-code]npm install[.inline-code] command:

$ npm install create-react-app

Define a script in the [.inline-code]scripts[.inline-code] section in the [.inline-code]package.json[.inline-code] file, which is a way to store commonly used commands for a project, such as test or build commands:

scripts : {
  "cra": "create-react-app"
}

And execute this script using the [.inline-code]npm run[.inline-code] command:

$ npm run cra -- my-app

[#using-npx-with-github-gists]Using [.inline-code]npx[.inline-code] with Github gists[#using-npx-with-github-gists]

Another cool thing about [.inline-code]npx[.inline-code] is being able to use it to run Github gists and repositories.

You can try this out by creating your own gist using the following steps:

1. Create a new gist on github
2. Create a package.json file

{
  "name": "example-with-npx",
  "description": "example to show gist and npx",
  "version": "0.0.1",
  "bin": "./index.js"
}

3. Create an index.js file

#!/usr/bin/env node

console.log('Welcome you just ran me with npx!');

And now you're ready to run this with [.inline-code]npx[.inline-code] using the URL of the gist:

$ npx https://gist.github.com/<your-url-here>