1SCOPE(7) SCOPE(7)
2
3
4
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
28 unscoped 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_mod‐
34 ules/@myorg/packagename. The scope folder (@myorg) is simply the name
35 of the scope preceded by an @ symbol, and can contain any number of
36 scoped 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 To publish a public scoped package, you must specify --access public
73 with the initial publication. This will publish the package and set
74 access to public as if you had run npm access public after publishing.
75
76 Publishing private scoped packages to the npm registry
77 To publish a private scoped package to the npm registry, you must have
78 an npm Private Modules https://docs.npmjs.com/private-modules/intro
79 account.
80
81 You can then publish the module with npm publish or npm publish
82 --access restricted, and it will be present in the npm registry, with
83 restricted access. You can then change the access permissions, if
84 desired, with npm access or on the npmjs.com website.
85
86 Associating a scope with a registry
87 Scopes can be associated with a separate registry. This allows you to
88 seamlessly use a mix of packages from the primary npm registry and one
89 or more private registries, such as npm Enterprise.
90
91 You can associate a scope with a registry at login, e.g.
92
93 npm login --registry=http://reg.example.com --scope=@myco
94
95 Scopes have a many-to-one relationship with registries: one registry
96 can host multiple scopes, but a scope only ever points to one registry.
97
98 You can also associate a scope with a registry using npm config:
99
100 npm config set @myco:registry http://reg.example.com
101
102 Once a scope is associated with a registry, any npm install for a pack‐
103 age with that scope will request packages from that registry instead.
104 Any npm publish for a package name that contains the scope will be pub‐
105 lished to that registry instead.
106
107 See also
108 · npm help install
109
110 · npm help publish
111
112 · npm help access
113
114 · npm help registry
115
116
117
118
119 March 2020 SCOPE(7)