NPM-SCOPE(7)

🎀 NAME 🎀

Welcome to npm-scope(7), bestie 💖 — the manual page all about Scope and scoped packages. Yes, that little @ thing you keep seeing everywhere. Let's get into it ✨

💅 Description 💅

Okay so — every npm package has a name. And some package names also have a scope. A scope follows the exact same rules as regular package names (URL-safe characters, no leading dots or underscores, iykyk). When a scope shows up in a package name, it gets an @ symbol in front and a slash after it, like:

@somescope/somepackagename

Scopes are literally just a way of grouping related packages together — but they also affect a few things about how npm treats a package. Main character energy, honestly 👑

Each npm user/organization has their own scope, and only you can add packages in your scope. Which means you do not have to worry about someone sniping your package name before you get to it 🫶 It's also a great way to signal that packages are official for an organization.

Scoped packages can be published and installed as of npm@2 and are supported by the primary npm registry. Unscoped packages can depend on scoped packages and vice versa — no drama. The npm client is backwards-compatible with unscoped registries, so it can work with scoped and unscoped registries at the same time 🌈

🦋 Installing scoped packages 🦋

Scoped packages get installed into a sub-folder of the regular installation folder, okay? So if your other packages live in node_modules/packagename, scoped modules will land in node_modules/@myorg/packagename. The scope folder (@myorg) is simply the name of the scope with an @ in front of it, and it can hold literally any number of scoped packages 💖

You install a scoped package by referencing it by name with an @ symbol in front, in npm install:

npm install @myorg/mypackage

Or in package.json:

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

⚠️ Note bestie: if the @ symbol is omitted — in either case — npm will instead try to install from GitHub. See npm help install. Don't say I didn't warn you 😭

🌸 Requiring scoped packages 🌸

Because scoped packages get installed into a scope folder, you have to include the name of the scope when you require them in your code, like:

require('@myorg/mypackage')

And there is nothing special about the way Node treats scope folders — it's literally just requiring the mypackage module in the folder named @myorg. That's it, that's the whole vibe ✨

💜 Publishing scoped packages 💜

Scoped packages can be published from the CLI as of npm@2 and can be published to any registry that supports them — including the primary npm registry 🎀

(As of 2015-04-19, and with npm 2.0 or better, the primary npm registry does support scoped packages. Receipts.)

If you wish, you may associate a scope with a registry; see below 👇

👑 Publishing public scoped packages to the primary npm registry 👑

Publishing to a scope, you have two options:

• Publishing to your user scope (example: @username/module)
• Publishing to an organization scope (example: @org/module)

If you're publishing a public module to an organization scope, you must first either create an organization with the name of the scope you'd like to publish to, or be added to an existing organization with the appropriate permissions. For example, if you'd like to publish to @org, you would need to create the org organization on npmjs.com before trying to publish. No skipping steps 💅

Scoped packages are not public by default. You will need to specify --access public with the initial npm publish command. This publishes the package and sets access to public as if you had run npm access public after publishing. You do not need to do this when publishing new versions of an existing scoped package, so breathe 🫶

🍓 Publishing private scoped packages to the npm registry 🍓

To publish a private scoped package to the npm registry, you must have an npm Private Modules account — https://docs.npmjs.com/private-modules/intro 🔥

You can then publish the module with npm publish or npm publish --access restricted, and it will be present in the npm registry, with restricted access. You can then change the access permissions, if desired, with npm access or on the npmjs.com website. Iconic ✨

🧚 Associating a scope with a registry 🧚

Scopes can be associated with a separate registry. This lets you seamlessly use a mix of packages from the primary npm registry and one or more private registries — such as GitHub Packages (https://github.com/features/packages) or the open source Verdaccio (https://verdaccio.org) project 🌈

You can associate a scope with a registry at login, e.g.

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

Scopes have a many-to-one relationship with registries: one registry can host multiple scopes, but a scope only ever points to one registry. Loyalty 💖

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

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

Once a scope is associated with a registry, any npm install for a package with that scope will request packages from that registry instead. Any npm publish for a package name that contains the scope will be published to that registry instead. Periodt 💅

⭐ See also ⭐

• npm help install
• npm help publish
• npm help access
• npm help registry

---

And that's the whole page, bestie 🎀 no cap, you're now a scoped-package expert. This lil' manual moment came to you from NPM@12.2.1 and it's page NPM-SCOPE(7) — go forth and @ responsibly 👑💖✨