@cryptotaxi247 / documentation-1
Code Commits Issues Pulls Sessions CI/CD
dependabot/npm_and_yarn/main/proc-log-7.0.0
@reggi/path-to-regexp dependabot/npm_and_yarn/main/copy-to-clipboard-4.0.2 dependabot/npm_and_yarn/main/eslint-10.4.0 dependabot/npm_and_yarn/main/npmcli/eslint-config-7.0.0 dependabot/npm_and_yarn/main/proc-log-7.0.0 dependabot/npm_and_yarn/npm_and_yarn-826852524d dependabot/npm_and_yarn/npm_and_yarn-ab9a7f4bc2 deprecate-totp-2fa dhei/classic-tokens gat-bypass-2fa-docs jpg619/fix-accessibility-content-flow jpg619/version-bump-tar-2 kartykp/gat-bypass-2fa-docs kartykp/upgrade-path-to-regex main maitxn/version-bump-tar patch-1 reggi/cache-based-on-version reggi/dev-engines reggi/fix-transform-prettier reggi/overrides update-search-sensitivity
mdx 124 lines 5.75 KB
Raw
1 ---
2 title: Scope
3 section: 7
4 description: Scoped packages
5 github_repo: npm/cli
6 github_branch: latest
7 github_path: docs/lib/content/using-npm/scope.md
8 redirect_from:
9 - /cli-documentation/misc/npm-scope
10 - /cli-documentation/misc/scope
11 - /cli-documentation/using-npm/npm-scope
12 - /cli-documentation/using-npm/scope
13 - /cli-documentation/v11/misc/npm-scope
14 - /cli-documentation/v11/misc/scope
15 - /cli-documentation/v11/using-npm/npm-scope
16 - /cli-documentation/v11/using-npm/scope
17 - /cli/misc/npm-scope
18 - /cli/misc/scope
19 - /cli/using-npm/npm-scope
20 - /cli/using-npm/scope
21 - /cli/v11/misc/npm-scope
22 - /cli/v11/misc/scope
23 - /cli/v11/using-npm/npm-scope
24 - /misc/npm-scope
25 - /misc/scope
26 - /using-npm/npm-scope
27 - /using-npm/scope
28 ---
29
30 ### Description
31
32 All npm packages have a name. Some package names also have a scope. A scope follows the usual rules for package names (URL-safe characters, no leading dots or underscores). When used in package names, scopes are preceded by an `@` symbol and followed by a slash, e.g.
33
34 ```bash
35 @somescope/somepackagename
36 ```
37
38 Scopes are a way of grouping related packages together, and also affect a few things about the way npm treats the package.
39
40 Each npm user/organization has their own scope, and only you can add packages in your scope. This means you don't have to worry about someone taking your package name ahead of you. Thus it is also a good way to signal official packages for organizations.
41
42 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. The npm client is backwards-compatible with unscoped registries, so it can be used to work with scoped and unscoped registries at the same time.
43
44 ### Installing scoped packages
45
46 Scoped packages are installed to a sub-folder of the regular installation folder, e.g. if your other packages are installed in `node_modules/packagename`, scoped modules will be installed in `node_modules/@myorg/packagename`. The scope folder (`@myorg`) is simply the name of the scope preceded by an `@` symbol, and can contain any number of scoped packages.
47
48 A scoped package is installed by referencing it by name, preceded by an `@` symbol, in `npm install`:
49
50 ```bash
51 npm install @myorg/mypackage
52 ```
53
54 Or in `package.json`:
55
56 ```json
57 "dependencies": {
58 "@myorg/mypackage": "^1.3.0"
59 }
60 ```
61
62 Note that if the `@` symbol is omitted, in either case, npm will instead attempt to install from GitHub; see [`npm install`](/cli/v11/commands/npm-install).
63
64 ### Requiring scoped packages
65
66 Because scoped packages are installed into a scope folder, you have to include the name of the scope when requiring them in your code, e.g.
67
68 ```javascript
69 require("@myorg/mypackage");
70 ```
71
72 There is nothing special about the way Node treats scope folders. This simply requires the `mypackage` module in the folder named `@myorg`.
73
74 ### Publishing scoped packages
75
76 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.
77
78 (As of 2015-04-19, and with npm 2.0 or better, the primary npm registry **does** support scoped packages.)
79
80 If you wish, you may associate a scope with a registry; see below.
81
82 #### Publishing public scoped packages to the primary npm registry
83
84 Publishing to a scope, you have two options:
85
86 - Publishing to your user scope (example: `@username/module`)
87 - Publishing to an organization scope (example: `@org/module`)
88
89 If publishing a public module to an organization scope, you must first either create an organization with the name of the scope that 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 prior to trying to publish.
90
91 Scoped packages are not public by default. You will need to specify `--access public` with the initial `npm publish` command. This will publish the package and set 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.
92
93 #### Publishing private scoped packages to the npm registry
94
95 To publish a private scoped package to the npm registry, you must have an [npm Private Modules](https://docs.npmjs.com/private-modules/intro) account.
96
97 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.
98
99 ### Associating a scope with a registry
100
101 Scopes can be associated with a separate registry. This allows you to 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.
102
103 You can associate a scope with a registry at login, e.g.
104
105 ```bash
106 npm login --registry=http://reg.example.com --scope=@myco
107 ```
108
109 Scopes have a many-to-one relationship with registries: one registry can host multiple scopes, but a scope only ever points to one registry.
110
111 You can also associate a scope with a registry using `npm config`:
112
113 ```bash
114 npm config set @myco:registry=http://reg.example.com
115 ```
116
117 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.
118
119 ### See also
120
121 - [npm install](/cli/v11/commands/npm-install)
122 - [npm publish](/cli/v11/commands/npm-publish)
123 - [npm access](/cli/v11/commands/npm-access)
124 - [npm registry](/cli/v11/using-npm/registry)