Go to main content

man pages section 7: Standards, Environments, Macros, Character Sets, and Miscellany

Exit Print View

Updated: Thursday, June 13, 2019

npm-scope (7)


npm-scope - Scoped packages


Please see following description for synopsis


NPM-SCOPE(7)                                                      NPM-SCOPE(7)

       npm-scope - Scoped packages

       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.


       Scopes are a way of grouping related packages together, and also affect
       a few things about the way npm treats the package.

       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  some-
       one  taking  your package name ahead of you. Thus it is also a good way
       to signal official packages for organizations.

       Scoped packages can be published and installed as of npm@2 and are sup-
       ported  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.

Installing scoped packages
       Scoped packages are installed to a sub-folder of the regular  installa-
       tion  folder,  e.g.  if  your other packages are installed in node_mod-
       ules/packagename,  scoped  modules  will  be  installed  in   node_mod-
       ules/@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.

       A scoped package is installed by referencing it by name, preceded by an
       @ symbol, in npm install:

         npm install @myorg/mypackage

       Or in package.json:

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

       Note that if the @ symbol is omitted, in either case, npm will  instead
       attempt to install from GitHub; see npm help npm-install.

Requiring scoped packages
       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.


       There is nothing special about the way Node treats scope folders.  This
       simply requires the mypackage module in the folder named @myorg.

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

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

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

   Publishing public scoped packages to the primary npm registry
       To publish a public scoped package, you must  specify  --access  public
       with  the  initial  publication.  This will publish the package and set
       access to public as if you had run npm access public after publishing.

   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  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.

Associating a scope with a registry
       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 npm Enterprise.

       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.

       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 pack-
       age  with  that scope will request packages from that registry instead.
       Any npm publish for a package name that contains the scope will be pub-
       lished to that registry instead.

       See attributes(7) for descriptions of the following attributes:

       |Availability   | runtime/nodejs/nodejs-8 |
       |Stability      | Pass-thru volatile      |
       o npm help install

       o npm help publish

       o npm help access

       o npm help 7 registry

       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source    was   downloaded   from    https://github.com/nodejs/node/ar-

       Further information about this software can be found on the open source
       community website at https://github.com/nodejs/node.

                                  August 2018                     NPM-SCOPE(7)