Executing local NPM packages

NPM (Source: npmjs.com)

There’s a recurring question I get asked about how to run NPM modules that are installed locally in your project without the need to install them globally.

This happens a lot with tools like gulp, webpack, create-react-app, etc. that usually in their docs suggest you install them globally so you can easily use them, but you don’t need to do this if you don’t want/can’t.

In this article, I am going to list the options we have for achieving this (from what I know, of course). I’ll be using the webpack package for the examples, so each option assumes that the package was already installed in the project, with a command like this: npm install webpack webpack-cli

If you had the packaged installed globally, you should be able to run the commandwebpack directly from the console and that would execute the webpack packaged installed globally. Here are the options you have if you want to execute the package installed in your project rather than the global one (if you have it installed)

Option 1: Finding the script in the installed package

Every package that you install is added to the node_modules folder, and after installing webpack, you should see a webpack folder inside of the node_modules. See the image below:

The first option consists in finding the javascript file that contains the logic of the package so you can execute it using node.

For some packages it can be fairly simple to find the main script, but for others it could be a nightmare. Usually, you can inspect the contents of the folder, for simple ones you will find an index.js file, for others you will find a bin folder with the executables, or you could find the info you’re looking for by inspecting the package.json file and looking at the bin or main keys.

In the case of the webpack module, we see that there’s a bin folder. So we can use the webpack.js file listed in there like this:

node ./node_modules/webpack/bin/webpack.js

This is my least favorite option since we have to do some extra work to find the script and then typing that long command gets annoying very quick. Let’s see other options.

Option 2: Executing the local binaries

You may have noticed that after you install certain modules with NPM, the node_modules folder is created and that it contains a .bin folder. This is what the NPM official docs say about that folder:

When in global mode, executables are linked into {prefix}/bin on Unix, or directly into {prefix} on Windows.

When in local mode, executables are linked into ./node_modules/.bin so that they can be made available to scripts run through npm. (For example, so that a test runner will be in the path when you run npm test.)

So basically, all the executables of the packages you install in your project will already be there, and the nice thing is that you can use them. To do it, you can call it like this:

./node_modules/.bin/webpack

This is easier and more straightforward than option 1, but still don’t like all that typing and we can do better. As there’s a shortcut to reach the bin folder; in that case the previous command would turn into this

$(npm bin)/webpack

The $(npm bin) part looks for the .bin directory automatically for you. This option is way better, but it feels a bit weird yet, so let’s see a nicer option.

Option 3: NPM Scripts

In your package.json file you can add custom scripts and execute them. Some times I’ve used them to execute the scripts of those packages that are installed in my project but I don’t have globally. Just look for the scripts key and in its value, you can add a key-value pair of your script name and the command you want it to execute:

For example, I’m going to define a wp command (you can name it whatever you want) which is going to execute the webpack command:

"scripts": {
  "wp": "webpack"
}

And in order to run it, you execute

npm run wp

In this case, as per the documentation referenced in option 2, npm is going to look for a binary named webpack in the .bin folder and execute it, so you don’t need to type the full path to the webpack binary as in option 2.

This option is way better, it only requires a little bit of configuration, but yes, we can do better than this.

Option 4: My new best friend NPX

As of NPM version 5.2, you will notice that when you install or update NPM, there’s something else included and it’s called NPX. This package is just a lovely utility that is now shipped with NPM (yes you must have it installed already if you are on npm >= 5.2) and helps you executing your local npm package binaries if they exist, and if it can’t find them in the local project it will look in the folder of those packages installed globally.

So in our case, we can simply run

npx webpack

I’ve been using this npx command for a while now and works like a charm in all the OS I’ve tested it.

NPX can do a lot more than this, you can read more in the official documentation or in my next article.

In conclusion, the most straightforward way is NPX, but if for some reason you can’t use it, you’ll always have the NPM scripts.