One of the mandatory fields that an npm package must have is a name:
The name should be unique, thereby representing the package when it’s published to the npm registry.
However, in case that a package is already published with a specific name, whether by another user or organization, clearly it’s not possible to publish our package with this name.
So, we can think about a different name and rename our package, but there is another option to approach that we should be aware of - and this is what we’re going to introduce. 😉
The content is available as a video as well:
What are Scoped Packages?
Scoped Packages is a way to group related npm packages together, and connect them to each other by a specified “scope”, that acts pretty much like a namespace.
This kind of packages provides a few benefits:
- We don’t have to worry if the package name exists - just name it, as long as we haven’t already published such a scoped package before
- We don’t have to worry that someone else will publish into our scope - only scope members have the permission
- In case we work with a private npm registry - we don’t have to switch to it before installing or publishing a package, but rather simply set the private registry for the scope in advance and once
That being said, there’s no free lunch, and we need to know how to use them correctly - but that’s the purpose of this guide.
So, let’s demonstrate how to work with scoped packages practically.
Creating a Scope
In order to create a new local scoped package, we can use
npm init --scope=sample-scope, which creates a package.json file and names the package considering the provided scope:
Notice that there is a convention so that the scope name itself begins with @ and followed by a slash.
In case the package has already been initialized, we will just need to rename it to contain the scope according to the convention, nothing more.
Publishing the Package
Now that we have an initialized local scoped package, we’d like to communicate with an npm registry to publish this package (and install as well later). Basically there are two options for choosing a registry to publish into - it could be the primary of npm or a private registry which we maintain ourselves.
In case we do want to assign the scope with a private registry, we can use npm config command and set it in advance:
npm config set @sample-scope:registry http://sample-registry.com
Great, let’s communicate with the registry and publish our package.
In order to do that, we should merely run the npm publish command:
Having said that, we should be aware that the package is published privately by default, meaning with restricted access.
The thing is we cannot publish privately into the primary registry, unless we have a paid account. So we can change the package to be published publicly when we initially publish with the
npm publish --access public
If we do want to publish privately, we can upgrade our account to a paid individual or organization; or just maintain our own private registry, for example, using Verdaccio.
Installing the Package
Well, after the scoped package is published, we can easily install it in another project.
All we need to do is running npm install with the full package name including the scope name:
npm install @sample-scope/sample-package
This will look for the package within the registry associated with the scope at first, and if the package isn’t there, it would be resolved from the default registry.
Today we explored the scoped packages in npm and focused on its benefits. We learned to associate a registry with the scope, publish a package and install it in another one.