How to Work with Scoped Packages

Requires npm version 2 or greater

Scopes are used to group related packages together, and to create a namespace, like a domain, for npm modules. This is explained in more detail here.

If a package's name begins with @, then it is a scoped package. The scope is everything in between the @ and the slash.


Each npm user has their own scope.


npm Orgs also have scopes.


You can find more in depth information about scopes in the CLI documentation.

How to Initialize a Scoped Package

To create a scoped package, you simply use a package name that starts with your scope.

  "name": "@username/project-name"

If you use npm init, you can add your scope as an option to that command.

npm init --scope=username

If you use the same scope all the time, you will probably want to set this option in your .npmrc file.

npm config set scope username

Publishing a Scoped Package

By default, scoped packages are private. To publish private modules, you need to be a paid private modules user.

Public scoped modules are free and don't require a paid subscription. To publish a public scoped module, set the access option when publishing it. This option will remain set for all subsequent publishes.

npm publish --access=public

Using a Scoped Package

To use a scoped package, simply include the scope wherever you use the package name.

In package.json:

  "dependencies": {
    "@username/project-name": "^1.0.0"

On the command line:

npm install @username/project-name --save

In a require statement:

var projectName = require("@username/project-name")

For information about using scoped private modules, visit docs.npmjs.com/private-modules/intro.

© npm, Inc. and Contributors
Licensed under the npm License.
npm is a trademark of npm, Inc.