Using Scoped NPM Packages

NPM is the most widely used package manager for NodeJS. It has more than 600,000 packages with hundreds of millions of downloads per day.

NodeJS uses directory hierarchy for finding modules. Specifically, it searches node_modules subdirectory in the current folder or its parent folders for the required modules.

Naming packages is important for several reasons. Firstly, your package name must be unique. Secondly, your chosen name should be expressive for your package.

Now this leads to a lot of problems. Consider, for example, that you want to create a package named dom for working with the document object model. Chances are someone has already put a package with that name on npm. On the other hand, let's assume that you need a package for working with DOM. Can you offhandedly run npm install dom and expect to find what you want?

As you can see, a simple name cannot satisfactorily define a package. What we need is some sort of namespace. Scoped packages give you this functionality. Instead of dom, you can name your package @yourname/dom. This prevent name clashes and defines your dom package more thoroughly.

In order to create a scoped package, add --scope yourname to npm init command:

    npm init --scope=yourname

This adds a line like the following to your package.json file:

    {
        "name": "@yourname/dom"
    }

When requiring scoped packages, you must use the complete name:

    const dom = require("@yourname/dom");

The same applies to including the package as a dependency in package.json:

{
    "dependencies": {
        "@yourname/dom": "^1.0.0"
    }
}   

In npm, scoped packages are private by default (and they require paid membership in npmjs.com). If you want to publish your scoped package publicly, you should set the public access option when publishing it (only the first time):

    npm publish --access=public

When installing scoped packages, you must use the complete name:

    npm install "@yourname/dom"

After installing a scoped package, npm creates a subdirectory @yourname under node_modules and puts your package in that folder:

    node_modules
        │
        └──@yourname
            │
            └──dom
                │
                ├──package.json
                └──index.js

Namespacing is very useful for differentiating packages. Scoped NodeJS packages are already being used in many popular JavaScript projects.