Scoped Packages in npm: Complete Guide and Usage

In the previous tutorial we showed you how to remove npm from your local environment, in this tutorial we will introduce you to scoped packages.

Description

Every package in npm has a name. Some of the package names also have a scope. A scope will follow the usual rules that apply to package names (URL-safe characters, no leading dots or underscores). When you use scopes in package names, they are preceded by an @ symbol, followed and they will be followed by a slash, here is an example:

@somescope/thepackagename,

You use scopes to group related packages together, and they also affect a few things about the way npm treats the package.

Every npm user/organization has their own scope, and you are only allowed to add packages to your scope. This indicates that you don't have to bother about someone taking your package name ahead of you. Hence, scope is a good way to signal official packages for organizations.

You can publish and install some scoped packages as of npm@2 and these are supported by the npm registry. An unscoped package can depend on a scoped package and vice versa. Because the npm client is backward compatible with unscoped registries, you can use it to work with both scoped and uncsoped registries at the same time.

Installing scoped packages

Scoped packages will be installed to a sub-folder of the regular installation folder, for instance, if your other packages are installed inside node_modules/packagename, scoped modules will be installed inside node_modules/@myorg/packagename. The scope folder (@myorg) will simply be the name of the scope preceded by an @ symbol, and can have any number of scoped packages.

You can install a scope package by referencing it by name, with a preceding @ symbol, inside npm install:

npm install @myorg/mypackage

Or in package.json:

"dependencies": {
  "@myorg/mypackage": "^1.3.0"
}

It should be noted that if the @ symbol is omitted, in either case, npm will attempt to install from GitHub instead.

Requiring scoped packages

Since, all scoped packages are installed into a scope folder, you will have to include the name of the scope when requiring them in your code, e.g.

require('@myorg/mypackage')

There is nothing special about the way that Node treats scope folders. This simply requires the mypackage module in the folder named @myorg.

Publishing scoped packages

You can publish scoped packages from the CLI as of npm@2 and they can be published to any registry that supports them, and this includes the primary npm registry.

(Since 2015-04-19, and with npm 2.0 or higher, the primary npm registry supports scoped packages.)

If you want, you can associate a scope with a registry; this is illustrated below.

How to publish public scoped packages to the primary npm registry

If you want to publish a public scoped package, you have to specify --access public with the initial publication. This publishes the package and sets access to public as if you had run npm access public after publishing.

How to publish private scoped packages to the npm registry

If you want to publish a private scoped package to the npm registry, you should have an npm Private Modules account.

Then, you can publish the module with npm publish or npm publish --access restricted, and the package will be present in the npm registry, with restricted access. Then, you can change the access permissions, if you want to, using npm access or from the npmjs.com website.

How to associate a scope with a registry

You can associate scopes with a separate registry. This will enable you to seamlessly use a mix of packages from the primary npm registry and one or more private registries, like npm Enterprise.

A scope can be associated with a registry at login, here is an example:

npm login --registry=http://reg.example.com --scope=@myco

All scopes have a many-to-one relationship with registries: a particular registry can host multiple scopes, but a scope points to a single registry.

You can equally associate a scope with a registry using npm config:

npm config set @myco:registry http://reg.example.com

After a scope is associated with a registry, any npm install for a package that has that scope will request packages from that registry instead. Any npm publish for a package name containing the scope will be published to that registry instead.

Previous: Uninstalling npm: Complete Guide to Removal.
Next: npm Scripts: Complete Guide to Package.json Scripts.