1SCOPE(7)                                                              SCOPE(7)
2
3
4

NAME

6       scope - Scoped packages
7
8   Description
9       All  npm  packages have a name. Some package names also have a scope. A
10       scope follows the usual rules for package names  (URL-safe  characters,
11       no leading dots or underscores). When used in package names, scopes are
12       preceded by an @ symbol and followed by a slash, e.g.
13
14         @somescope/somepackagename
15
16       Scopes are a way of grouping related packages together, and also affect
17       a few things about the way npm treats the package.
18
19       Each  npm  user/organization  has their own scope, and only you can add
20       packages in your scope. This means you don't have to worry about  some‐
21       one  taking  your package name ahead of you. Thus it is also a good way
22       to signal official packages for organizations.
23
24       Scoped packages can be published and installed as of npm@2 and are sup‐
25       ported  by  the  primary  npm registry. Unscoped packages can depend on
26       scoped packages and vice versa. The npm client is  backwards-compatible
27       with unscoped registries, so it can be used to work with scoped and un‐
28       scoped registries at the same time.
29
30   Installing scoped packages
31       Scoped packages are installed to a sub-folder of the regular  installa‐
32       tion  folder,  e.g.  if  your other packages are installed in node_mod‐
33       ules/packagename, scoped modules will be installed in node_modules/@my‐
34       org/packagename.  The  scope  folder (@myorg) is simply the name of the
35       scope preceded by an @ symbol, and can contain  any  number  of  scoped
36       packages.
37
38       A scoped package is installed by referencing it by name, preceded by an
39       @ symbol, in npm install:
40
41         npm install @myorg/mypackage
42
43       Or in package.json:
44
45         "dependencies": {
46           "@myorg/mypackage": "^1.3.0"
47         }
48
49       Note that if the @ symbol is omitted, in either case, npm will  instead
50       attempt to install from GitHub; see npm help install.
51
52   Requiring scoped packages
53       Because  scoped packages are installed into a scope folder, you have to
54       include the name of the scope when requiring them in your code, e.g.
55
56         require('@myorg/mypackage')
57
58       There is nothing special about the way Node treats scope folders.  This
59       simply requires the mypackage module in the folder named @myorg.
60
61   Publishing scoped packages
62       Scoped  packages  can  be published from the CLI as of npm@2 and can be
63       published to any registry that supports them, including the primary npm
64       registry.
65
66       (As of 2015-04-19, and with npm 2.0 or better, the primary npm registry
67       does support scoped packages.)
68
69       If you wish, you may associate a scope with a registry; see below.
70
71   Publishing public scoped packages to the primary npm registry
72       Publishing to a scope, you have two options:
73
74       •   Publishing to your user scope (example: @username/module)
75
76       •   Publishing to an organization scope (example: @org/module)
77
78
79       If publishing a public module to an organization scope, you must  first
80       either  create  an  organization  with the name of the scope that you'd
81       like to publish to or be added to an existing organization with the ap‐
82       propriate  permissions.  For example, if you'd like to publish to @org,
83       you would need to create the org organization  on  npmjs.com  prior  to
84       trying to publish.
85
86       Scoped  packages  are  not  public by default. You will need to specify
87       --access public with the initial npm publish command. This will publish
88       the  package and set access to public as if you had run npm access pub‐
89       lic after publishing. You do not need to do this  when  publishing  new
90       versions of an existing scoped package.
91
92   Publishing private scoped packages to the npm registry
93       To  publish a private scoped package to the npm registry, you must have
94       an npm Private  Modules  ⟨https://docs.npmjs.com/private-modules/intro⟩
95       account.
96
97       You  can  then publish the module with npm publish or npm publish --ac‐
98       cess restricted, and it will be present in the npm registry,  with  re‐
99       stricted  access.  You  can  then change the access permissions, if de‐
100       sired, with npm access or on the npmjs.com website.
101
102   Associating a scope with a registry
103       Scopes can be associated with a separate registry. This allows  you  to
104       seamlessly  use a mix of packages from the primary npm registry and one
105       or   more    private    registries,    such    as    GitHub    Packages
106       ⟨https://github.com/features/packages⟩  or  the  open  source Verdaccio
107       ⟨https://verdaccio.org⟩ project.
108
109       You can associate a scope with a registry at login, e.g.
110
111         npm login --registry=http://reg.example.com --scope=@myco
112
113       Scopes have a many-to-one relationship with  registries:  one  registry
114       can host multiple scopes, but a scope only ever points to one registry.
115
116       You can also associate a scope with a registry using npm config:
117
118         npm config set @myco:registry http://reg.example.com
119
120       Once a scope is associated with a registry, any npm install for a pack‐
121       age with that scope will request packages from that  registry  instead.
122       Any npm publish for a package name that contains the scope will be pub‐
123       lished to that registry instead.
124
125   See also
126       •   npm help install
127
128       •   npm help publish
129
130       •   npm help access
131
132       •   npm help registry
133
134
135
136                                 November 2023                        SCOPE(7)