NPM Scopes: Namespacing Packages to Avoid Collisions

WHY IT EXISTS: The public npm registry is a single, flat namespace. With millions of packages, finding a unique, descriptive name is difficult. Scopes were introduced to solve this "name squatting" problem by creating namespaces, similar to folders in a file system, preventing collisions.

THE MENTAL MODEL: Think of the npm registry as a giant room filled with books, each with a unique title. An unscoped package is a single book in this room. A scope, like @your-name, is your own personal bookshelf. You can name your books whatever you want on your shelf (e.g., utils), even if another book with that title exists elsewhere. Your book's full, unique title becomes @your-name/utils.

HOW IT WORKS: A scope is the part of a package name after the @ and before the slash, like angular in @angular/core. Scopes are tied to an npm user or organization. When you publish a scoped package, it's placed under that namespace. By default, publishing a scoped package makes it public. To make it private, you must use the --access private flag during publish, which requires a paid npm user or organization account.

WHEN TO USE IT: Use scopes whenever you are creating packages for an organization to group related modules (e.g., @my-company/design-system, @my-company/auth-client). They are mandatory for publishing private packages to the npm registry. Large open-source projects like Babel (@babel/core, @babel/parser) also use scopes to manage their ecosystem of packages.

WHEN NOT TO USE IT: For a single, standalone public package where the name is unique and you don't anticipate creating a suite of related packages, a scope might be unnecessary overhead. If you have no intention of ever using private packages or creating an organizational suite, an unscoped package is simpler.

ONE CANONICAL EXAMPLE: The Angular framework is a classic example. Instead of publishing dozens of top-level packages like angular-core, angular-router, and angular-common, they are all grouped under the @angular scope. To install the router, you run npm install @angular/router. This clearly communicates that the package is part of the official Angular ecosystem and avoids cluttering the global namespace.