diff options
author | Laurie Voss <git@seldo.com> | 2014-09-04 00:41:03 +0400 |
---|---|---|
committer | Forrest L Norvell <forrest@npmjs.com> | 2014-09-05 04:19:04 +0400 |
commit | 1b2ffdf359a8c897a78f91fc5a5d535c97aaec97 (patch) | |
tree | 6fc98fec8c618e8ed762f6826ef8f5696f62260a /doc | |
parent | 0a67d536067c4808a594d81288d34c0f7e97e105 (diff) |
Changes to reflect scoped package support.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/cli/npm-adduser.md | 27 | ||||
-rw-r--r-- | doc/cli/npm-install.md | 45 | ||||
-rw-r--r-- | doc/cli/npm-link.md | 18 | ||||
-rw-r--r-- | doc/cli/npm-ls.md | 8 | ||||
-rw-r--r-- | doc/cli/npm-prefix.md | 8 | ||||
-rw-r--r-- | doc/cli/npm-publish.md | 6 | ||||
-rw-r--r-- | doc/cli/npm-uninstall.md | 5 | ||||
-rw-r--r-- | doc/cli/npm-unpublish.md | 4 | ||||
-rw-r--r-- | doc/cli/npm-update.md | 7 | ||||
-rw-r--r-- | doc/cli/npm-view.md | 4 | ||||
-rw-r--r-- | doc/files/npm-folders.md | 6 | ||||
-rw-r--r-- | doc/files/package.json.md | 3 | ||||
-rw-r--r-- | doc/misc/npm-registry.md | 17 | ||||
-rw-r--r-- | doc/misc/npm-scope.md | 84 |
14 files changed, 200 insertions, 42 deletions
diff --git a/doc/cli/npm-adduser.md b/doc/cli/npm-adduser.md index 68f3a3c00..d60d6e9a0 100644 --- a/doc/cli/npm-adduser.md +++ b/doc/cli/npm-adduser.md @@ -3,30 +3,47 @@ npm-adduser(1) -- Add a registry user account ## SYNOPSIS - npm adduser + npm adduser [--registry=url] [--scope=@orgname] ## DESCRIPTION -Create or verify a user named `<username>` in the npm registry, and -save the credentials to the `.npmrc` file. +Create or verify a user named `<username>` in the specified registry, and +save the credentials to the `.npmrc` file. If no registry is specified, +the default registry will be used (see `npm-config(7)`). The username, password, and email are read in from prompts. You may use this command to change your email address, but not username or password. -To reset your password, go to <https://npmjs.org/forgot> +To reset your password, go to <https://www.npmjs.org/forgot> You may use this command multiple times with the same user account to authorize on a new machine. +`npm login` is an alias to `adduser` and behaves exactly the same way. + ## CONFIGURATION ### registry Default: http://registry.npmjs.org/ -The base URL of the npm package registry. +The base URL of the npm package registry. If `scope` is also specified, +this registry will only be used for packages with that scope. See `npm-scope(7)`. + +### scope + +Default: none + +If specified, the user and login credentials given will be associated +with the specified scope. See `npm-scope(7)`. You can use both at the same time, +e.g. + + npm adduser --registry=http://myregistry.example.com --scope=@myco + +This will set a registry for the given scope and login or create a user for +that registry at the same time. ## SEE ALSO diff --git a/doc/cli/npm-install.md b/doc/cli/npm-install.md index 62eec2d8e..2d4271637 100644 --- a/doc/cli/npm-install.md +++ b/doc/cli/npm-install.md @@ -7,10 +7,10 @@ npm-install(1) -- Install a package npm install <tarball file> npm install <tarball url> npm install <folder> - npm install <name> [--save|--save-dev|--save-optional] [--save-exact] - npm install <name>@<tag> - npm install <name>@<version> - npm install <name>@<version range> + npm install [@<scope>/]<name> [--save|--save-dev|--save-optional] [--save-exact] + npm install [@<scope>/]<name>@<tag> + npm install [@<scope>/]<name>@<version> + npm install [@<scope>/]<name>@<version range> npm i (with any of the previous argument usage) ## DESCRIPTION @@ -70,7 +70,7 @@ after packing it up into a tarball (b). npm install https://github.com/indexzero/forever/tarball/v0.5.6 -* `npm install <name> [--save|--save-dev|--save-optional]`: +* `npm install [@<scope>/]<name> [--save|--save-dev|--save-optional]`: Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See `npm-config(7)`.) @@ -98,9 +98,19 @@ after packing it up into a tarball (b). exact version rather than using npm's default semver range operator. + `<scope>` is optional. The package will be downloaded from the registry + associated with the specified scope. If no registry is associated with + the given scope the default registry is assumed. See `npm-scope(7)`. + + Note: if you do not include the @-symbol on your scope name, npm will + interpret this as a GitHub repository instead, see below. Scopes names + must also be followed by a slash. + Examples: npm install sax --save + npm install githubname/reponame + npm install @myorg/privatepackage npm install node-tap --save-dev npm install dtrace-provider --save-optional npm install readable-stream --save --save-exact @@ -110,7 +120,7 @@ after packing it up into a tarball (b). working directory, then it will try to install that, and only try to fetch the package by name if it is not valid. -* `npm install <name>@<tag>`: +* `npm install [@<scope>/]<name>@<tag>`: Install the version of the package that is referenced by the specified tag. If the tag does not exist in the registry data for that package, then this @@ -119,17 +129,19 @@ after packing it up into a tarball (b). Example: npm install sax@latest + npm install @myorg/mypackage@latest -* `npm install <name>@<version>`: +* `npm install [@<scope>/]<name>@<version>`: - Install the specified version of the package. This will fail if the version - has not been published to the registry. + Install the specified version of the package. This will fail if the + version has not been published to the registry. Example: npm install sax@0.1.1 + npm install @myorg/privatepackage@1.5.0 -* `npm install <name>@<version range>`: +* `npm install [@<scope>/]<name>@<version range>`: Install a version of the package matching the specified version range. This will follow the same rules for resolving dependencies described in `package.json(5)`. @@ -140,6 +152,19 @@ after packing it up into a tarball (b). Example: npm install sax@">=0.1.0 <0.2.0" + npm install @myorg/privatepackage@">=0.1.0 <0.2.0" + +* `npm install <githubname>/<githubrepo>`: + + Install the package at `https://github.com/githubname/githubrepo" by + attempting to clone it using `git`. + + Example: + + npm install mygithubuser/myproject + + To reference a package in a git repo that is not on GitHub, see git + remote urls below. * `npm install <git remote url>`: diff --git a/doc/cli/npm-link.md b/doc/cli/npm-link.md index c0fc01eb2..a6c274790 100644 --- a/doc/cli/npm-link.md +++ b/doc/cli/npm-link.md @@ -4,7 +4,7 @@ npm-link(1) -- Symlink a package folder ## SYNOPSIS npm link (in package folder) - npm link <pkgname> + npm link [@<scope>/]<pkgname> npm ln (with any of the previous argument usage) ## DESCRIPTION @@ -12,7 +12,8 @@ npm-link(1) -- Symlink a package folder Package linking is a two-step process. First, `npm link` in a package folder will create a globally-installed -symbolic link from `prefix/package-name` to the current folder. +symbolic link from `prefix/package-name` to the current folder (see +`npm-config(7)` for the value of `prefix`). Next, in some other location, `npm link package-name` will create a symlink from the local `node_modules` folder to the global symlink. @@ -20,12 +21,14 @@ symlink from the local `node_modules` folder to the global symlink. Note that `package-name` is taken from `package.json`, not from directory name. +The package name can be optionally prefixed with a scope. See `npm-scope(7)`. +The scope must by preceded by an @-symbol and followed by a slash. + When creating tarballs for `npm publish`, the linked packages are "snapshotted" to their current state by resolving the symbolic links. -This is -handy for installing your own stuff, so that you can work on it and test it -iteratively without having to continually rebuild. +This is handy for installing your own stuff, so that you can work on it and +test it iteratively without having to continually rebuild. For example: @@ -51,6 +54,11 @@ The second line is the equivalent of doing: That is, it first creates a global link, and then links the global installation target into your project's `node_modules` folder. +If your linked package is scoped (see `npm-scope(7)`) your link command must +include that scope, e.g. + + npm link @myorg/privatepackage + ## SEE ALSO * npm-developers(7) diff --git a/doc/cli/npm-ls.md b/doc/cli/npm-ls.md index 21f54264c..0f0d79489 100644 --- a/doc/cli/npm-ls.md +++ b/doc/cli/npm-ls.md @@ -3,10 +3,10 @@ npm-ls(1) -- List installed packages ## SYNOPSIS - npm list [<pkg> ...] - npm ls [<pkg> ...] - npm la [<pkg> ...] - npm ll [<pkg> ...] + npm list [[@<scope>/]<pkg> ...] + npm ls [[@<scope>/]<pkg> ...] + npm la [[@<scope>/]<pkg> ...] + npm ll [[@<scope>/]<pkg> ...] ## DESCRIPTION diff --git a/doc/cli/npm-prefix.md b/doc/cli/npm-prefix.md index f99a401d1..f262a36a7 100644 --- a/doc/cli/npm-prefix.md +++ b/doc/cli/npm-prefix.md @@ -3,11 +3,15 @@ npm-prefix(1) -- Display prefix ## SYNOPSIS - npm prefix + npm prefix [-g] ## DESCRIPTION -Print the prefix to standard out. +Print the local prefix to standard out. This is the closest parent directory +to contain a package.json file unless `-g` is also specified. + +If `-g` is specified, this will be the value of the global prefix. See +`npm-config(7)` for more detail. ## SEE ALSO diff --git a/doc/cli/npm-publish.md b/doc/cli/npm-publish.md index 338728e3e..8860b88fc 100644 --- a/doc/cli/npm-publish.md +++ b/doc/cli/npm-publish.md @@ -11,6 +11,10 @@ npm-publish(1) -- Publish a package Publishes a package to the registry so that it can be installed by name. +By default npm will publish to the public registry. This can be overridden by +specifying a different default registry or using a `npm-scope(7)` in the name +(see `package.json(5)`). + * `<folder>`: A folder containing a package.json file @@ -24,7 +28,7 @@ Publishes a package to the registry so that it can be installed by name. and `npm install` installs the `latest` tag. Fails if the package name and version combination already exists in -the registry. +the specified registry. Once a package is published with a given name and version, that specific name and version combination can never be used again, even if diff --git a/doc/cli/npm-uninstall.md b/doc/cli/npm-uninstall.md index e24815bec..bfa667c3e 100644 --- a/doc/cli/npm-uninstall.md +++ b/doc/cli/npm-uninstall.md @@ -3,7 +3,7 @@ npm-rm(1) -- Remove a package ## SYNOPSIS - npm uninstall <name> [--save|--save-dev|--save-optional] + npm uninstall [@<scope>/]<package> [--save|--save-dev|--save-optional] npm rm (with any of the previous argument usage) ## DESCRIPTION @@ -27,9 +27,12 @@ the package version in your main package.json: * `--save-optional`: Package will be removed from your `optionalDependencies`. +Scope is optional and follows the usual rules for `npm-scope(7)`. + Examples: npm uninstall sax --save + npm uninstall @myorg/privatepackage --save npm uninstall node-tap --save-dev npm uninstall dtrace-provider --save-optional diff --git a/doc/cli/npm-unpublish.md b/doc/cli/npm-unpublish.md index 45026197e..1d5fe9287 100644 --- a/doc/cli/npm-unpublish.md +++ b/doc/cli/npm-unpublish.md @@ -3,7 +3,7 @@ npm-unpublish(1) -- Remove a package from the registry ## SYNOPSIS - npm unpublish <name>[@<version>] + npm unpublish [@<scope>/]<name>[@<version>] ## WARNING @@ -27,6 +27,8 @@ Even if a package version is unpublished, that specific name and version combination can never be reused. In order to publish the package again, a new version number must be used. +The scope is optional and follows the usual rules for `npm-scope(7)`. + ## SEE ALSO * npm-deprecate(1) diff --git a/doc/cli/npm-update.md b/doc/cli/npm-update.md index 1ea6b6275..a53d29459 100644 --- a/doc/cli/npm-update.md +++ b/doc/cli/npm-update.md @@ -12,8 +12,11 @@ This command will update all the packages listed to the latest version It will also install missing packages. -If the `-g` flag is specified, this command will update globally installed packages. -If no package name is specified, all packages in the specified location (global or local) will be updated. +If the `-g` flag is specified, this command will update globally installed +packages. + +If no package name is specified, all packages in the specified location (global +or local) will be updated. ## SEE ALSO diff --git a/doc/cli/npm-view.md b/doc/cli/npm-view.md index 1d19fe88d..8f52a85a9 100644 --- a/doc/cli/npm-view.md +++ b/doc/cli/npm-view.md @@ -3,8 +3,8 @@ npm-view(1) -- View registry info ## SYNOPSIS - npm view <name>[@<version>] [<field>[.<subfield>]...] - npm v <name>[@<version>] [<field>[.<subfield>]...] + npm view [@<scope>/]<name>[@<version>] [<field>[.<subfield>]...] + npm v [@<scope>/]<name>[@<version>] [<field>[.<subfield>]...] ## DESCRIPTION diff --git a/doc/files/npm-folders.md b/doc/files/npm-folders.md index 1b1485d5e..1fb21b1a3 100644 --- a/doc/files/npm-folders.md +++ b/doc/files/npm-folders.md @@ -42,6 +42,12 @@ Global installs on Unix systems go to `{prefix}/lib/node_modules`. Global installs on Windows go to `{prefix}/node_modules` (that is, no `lib` folder.) +Scoped packages are installed the same way, except they are grouped together +in a sub-folder of the relevant `node_modules` folder with the name of that +scope prefix by the @ symbol, e.g. `npm install @myorg/package` would place +the package in `{prefix}/node_modules/@myorg/package`. See `scopes(7)` for +more details. + If you wish to `require()` a package, then install it locally. ### Executables diff --git a/doc/files/package.json.md b/doc/files/package.json.md index af10cc962..266adfe05 100644 --- a/doc/files/package.json.md +++ b/doc/files/package.json.md @@ -30,6 +30,9 @@ The name is what your thing is called. Some tips: * You may want to check the npm registry to see if there's something by that name already, before you get too attached to it. http://registry.npmjs.org/ +A name can be optionally prefixed by a scope, e.g. `@myorg/mypackage`. See +`npm-scope(7)` for more detail. + ## version The *most* important things in your package.json are the name and version fields. diff --git a/doc/misc/npm-registry.md b/doc/misc/npm-registry.md index a8c4b0200..42cec5944 100644 --- a/doc/misc/npm-registry.md +++ b/doc/misc/npm-registry.md @@ -12,15 +12,14 @@ write APIs as well, to allow for publishing packages and managing user account information. The official public npm registry is at <http://registry.npmjs.org/>. It -is powered by a CouchDB database at -<http://isaacs.iriscouch.com/registry>. The code for the couchapp is -available at <http://github.com/npm/npmjs.org>. npm user accounts -are CouchDB users, stored in the <http://isaacs.iriscouch.com/_users> -database. - -The registry URL is supplied by the `registry` config parameter. See -`npm-config(1)`, `npmrc(5)`, and `npm-config(7)` for more on managing -npm's configuration. +is powered by a CouchDB database, of which there is a public mirror at +<http://skimdb.npmjs.com/registry>. The code for the couchapp is +available at <http://github.com/npm/npm-registry-couchapp>. + +The registry URL used is determined by the scope of the package (see +`npm-scope(7)`). If no scope is specified, the default registry is used, which is +supplied by the `registry` config parameter. See `npm-config(1)`, +`npmrc(5)`, and `npm-config(7)` for more on managing npm's configuration. ## Can I run my own private registry? diff --git a/doc/misc/npm-scope.md b/doc/misc/npm-scope.md new file mode 100644 index 000000000..a4ee1a082 --- /dev/null +++ b/doc/misc/npm-scope.md @@ -0,0 +1,84 @@ +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. + + @somescope/somepackagename + +Scopes are a way of grouping related packages together, and also affect a few +things about the way npm treats the package. + +**As of 2014-09-03, scoped packages are not supported by the public npm registry**. +However, 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. + +## 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 +contain any number of scoped packages. + +A scoped package is install 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-install(1)`. + +## 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. + + 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`. + +## Publishing scoped packages + +Scoped packages can be published to any registry that supports them. +*As of 2014-09-03, the public npm registry does not support scoped packages*, +so attempting to publish a scoped package to the registry will fail unless +you have associated that scope with a different registry, see below. + +## 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 public 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 package +with that scope will request packages from that registry instead. Any +`npm publish` for a package name that contains the scope will be published to +that registry instead. + +## SEE ALSO + +* npm-install(1) +* npm-publish(1)
\ No newline at end of file |