138 lines
4.6 KiB
Groff
138 lines
4.6 KiB
Groff
.TH "SCOPE" "7" "February 2022" "" ""
|
|
.SH "NAME"
|
|
\fBscope\fR \- Scoped packages
|
|
.SS Description
|
|
.P
|
|
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 \fB@\fP symbol
|
|
and followed by a slash, e\.g\.
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
@somescope/somepackagename
|
|
.fi
|
|
.RE
|
|
.P
|
|
Scopes are a way of grouping related packages together, and also affect a few
|
|
things about the way npm treats the package\.
|
|
.P
|
|
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\.
|
|
.P
|
|
Scoped packages can be published and installed as of \fBnpm@2\fP 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\.
|
|
.SS Installing scoped packages
|
|
.P
|
|
Scoped packages are installed to a sub\-folder of the regular installation
|
|
folder, e\.g\. if your other packages are installed in \fBnode_modules/packagename\fP,
|
|
scoped modules will be installed in \fBnode_modules/@myorg/packagename\fP\|\. The scope
|
|
folder (\fB@myorg\fP) is simply the name of the scope preceded by an \fB@\fP symbol, and can
|
|
contain any number of scoped packages\.
|
|
.P
|
|
A scoped package is installed by referencing it by name, preceded by an
|
|
\fB@\fP symbol, in \fBnpm install\fP:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
npm install @myorg/mypackage
|
|
.fi
|
|
.RE
|
|
.P
|
|
Or in \fBpackage\.json\fP:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
"dependencies": {
|
|
"@myorg/mypackage": "^1\.3\.0"
|
|
}
|
|
.fi
|
|
.RE
|
|
.P
|
|
Note that if the \fB@\fP symbol is omitted, in either case, npm will instead attempt to
|
|
install from GitHub; see npm help \fBinstall\fP\|\.
|
|
.SS Requiring scoped packages
|
|
.P
|
|
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\.
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
require('@myorg/mypackage')
|
|
.fi
|
|
.RE
|
|
.P
|
|
There is nothing special about the way Node treats scope folders\. This
|
|
simply requires the \fBmypackage\fP module in the folder named \fB@myorg\fP\|\.
|
|
.SS Publishing scoped packages
|
|
.P
|
|
Scoped packages can be published from the CLI as of \fBnpm@2\fP and can be
|
|
published to any registry that supports them, including the primary npm
|
|
registry\.
|
|
.P
|
|
(As of 2015\-04\-19, and with npm 2\.0 or better, the primary npm registry
|
|
\fBdoes\fR support scoped packages\.)
|
|
.P
|
|
If you wish, you may associate a scope with a registry; see below\.
|
|
.SS Publishing public scoped packages to the primary npm registry
|
|
.P
|
|
To publish a public scoped package, you must specify \fB\-\-access public\fP with
|
|
the initial publication\. This will publish the package and set access
|
|
to \fBpublic\fP as if you had run \fBnpm access public\fP after publishing\.
|
|
.SS Publishing private scoped packages to the npm registry
|
|
.P
|
|
To publish a private scoped package to the npm registry, you must have
|
|
an npm Private Modules \fIhttps://docs\.npmjs\.com/private\-modules/intro\fR
|
|
account\.
|
|
.P
|
|
You can then publish the module with \fBnpm publish\fP or \fBnpm publish
|
|
\-\-access restricted\fP, and it will be present in the npm registry, with
|
|
restricted access\. You can then change the access permissions, if
|
|
desired, with \fBnpm access\fP or on the npmjs\.com website\.
|
|
.SS Associating a scope with a registry
|
|
.P
|
|
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 \fIhttps://github\.com/features/packages\fR or the open source Verdaccio \fIhttps://verdaccio\.org\fR
|
|
project\.
|
|
.P
|
|
You can associate a scope with a registry at login, e\.g\.
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
npm login \-\-registry=http://reg\.example\.com \-\-scope=@myco
|
|
.fi
|
|
.RE
|
|
.P
|
|
Scopes have a many\-to\-one relationship with registries: one registry can
|
|
host multiple scopes, but a scope only ever points to one registry\.
|
|
.P
|
|
You can also associate a scope with a registry using \fBnpm config\fP:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
npm config set @myco:registry http://reg\.example\.com
|
|
.fi
|
|
.RE
|
|
.P
|
|
Once a scope is associated with a registry, any \fBnpm install\fP for a package
|
|
with that scope will request packages from that registry instead\. Any
|
|
\fBnpm publish\fP for a package name that contains the scope will be published to
|
|
that registry instead\.
|
|
.SS See also
|
|
.RS 0
|
|
.IP \(bu 2
|
|
npm help install
|
|
.IP \(bu 2
|
|
npm help publish
|
|
.IP \(bu 2
|
|
npm help access
|
|
.IP \(bu 2
|
|
npm help registry
|
|
|
|
.RE
|