diff options
author | chocolateboy <chocolate@cpan.org> | 2017-01-25 17:13:01 +0300 |
---|---|---|
committer | Kat Marchán <kzm@sykosomatic.org> | 2017-01-25 17:13:01 +0300 |
commit | 821fee6d0b12a324e035c397ae73904db97d07d2 (patch) | |
tree | 861ff3d3fedd1cddde95c7c45f4e65110332a49f /doc | |
parent | d75fc03eda5364f12ac266fa4f66e31c2e44e864 (diff) |
doc: clarify that unscoped packages can depend on scoped packages (#15480)
as per the discussion in [1], clarify the fact that unscoped packages
can depend on scoped packages (and *vice versa*), contrary to
the initial proposal and announcements.
also:
- s/un-scoped/unscoped/ as per e.g. [2]
- fix typos + minor cosmetic tweaks
[1] https://github.com/npm/npm/issues/15305#issuecomment-272599537
[2] https://github.com/npm/npm/blob/v4.1.1/doc/cli/npm-access.md
PR-URL: https://github.com/npm/npm/pull/15480
Credit: @chocolateboy
Reviewed-By: @iarna
Diffstat (limited to 'doc')
-rw-r--r-- | doc/misc/npm-scope.md | 31 |
1 files changed, 16 insertions, 15 deletions
diff --git a/doc/misc/npm-scope.md b/doc/misc/npm-scope.md index e9d4d025c..98e7bc58e 100644 --- a/doc/misc/npm-scope.md +++ b/doc/misc/npm-scope.md @@ -4,9 +4,9 @@ npm-scope(7) -- Scoped packages ## DESCRIPTION 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, preceded by an @-symbol and -followed by a slash, e.g. +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. @somescope/somepackagename @@ -14,20 +14,20 @@ Scopes are a way of grouping related packages together, and also affect a few things about the way npm treats the package. Scoped packages can be published and installed as of `npm@2` and are supported -by the primary npm registry. The npm client is backwards-compatible with -un-scoped registries, so it can be used to work with scoped and un-scoped -registries at the same time. +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 installation folder, e.g. if your other packages are installed in `node_modules/packagename`, -scoped modules will be in `node_modules/@myorg/packagename`. The scope folder -(`@myorg`) is simply the name of the scope preceded by an @-symbol, and can +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. A scoped package is installed by referencing it by name, preceded by an -@-symbol, in `npm install`: +`@` symbol, in `npm install`: npm install @myorg/mypackage @@ -37,7 +37,7 @@ Or in `package.json`: "@myorg/mypackage": "^1.3.0" } -Note that if the @-symbol is omitted in either case npm will instead attempt to +Note that if the `@` symbol is omitted, in either case, npm will instead attempt to install from GitHub; see `npm-install(1)`. ## Requiring scoped packages @@ -47,8 +47,8 @@ include the name of the scope when requiring them in your code, e.g. require('@myorg/mypackage') -There is nothing special about the way Node treats scope folders, this is -just specifying to require the module `mypackage` in the folder called `@myorg`. +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 @@ -57,14 +57,14 @@ published to any registry that supports them, including the primary npm registry. (As of 2015-04-19, and with npm 2.0 or better, the primary npm registry -**does** support scoped packages) +**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 +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 @@ -75,7 +75,7 @@ account. 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 +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 @@ -105,3 +105,4 @@ that registry instead. * npm-install(1) * npm-publish(1) * npm-access(1) +* npm-registry(7) |