diff options
author | Jordan Harband <ljharb@gmail.com> | 2016-01-13 09:02:37 +0300 |
---|---|---|
committer | Rebecca Turner <me@re-becca.org> | 2016-01-21 04:08:39 +0300 |
commit | e6d238a3d90beeb0af23fa75a9b5e50671d6e4c5 (patch) | |
tree | 28ef06cd6b40d040db8d1d123599b5d2a7e9b9d5 /README.md | |
parent | 382e71a7ee5d1ca3dba55c1e753d529eb8ae6895 (diff) |
readme: nuke "using npm programmatically" section
The programmatic `npm` API is unsupported, and is not guaranteed not to break in non-major versions.
Removing this section so newcomers aren't encouraged to discover or use it.
PR-URL: https://github.com/npm/npm/pull/11130
Credit: @ljharb
Reviewed-By: @othiym23
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 46 |
1 files changed, 0 insertions, 46 deletions
@@ -138,52 +138,6 @@ must remove them yourself manually if you want them gone. Note that this means that future npm installs will not remember the settings that you have chosen. -## Using npm Programmatically - -Although npm can be used programmatically, its API is meant for use by the CLI -*only*, and no guarantees are made regarding its fitness for any other purpose. -If you want to use npm to reliably perform some task, the safest thing to do is -to invoke the desired `npm` command with appropriate arguments. - -The semantic version of npm refers to the CLI itself, rather than the -underlying API. _The internal API is not guaranteed to remain stable even when -npm's version indicates no breaking changes have been made according to -semver._ - -If you _still_ would like to use npm programmatically, it's _possible_. The API -isn't very well documented, but it _is_ rather simple. - -Eventually, npm will be just a thin CLI wrapper around the modules that it -depends on, but for now, there are some things that only the CLI can do. You -should try using one of npm's dependencies first, and only use the API if what -you're trying to do is only supported by npm itself. - -```javascript -var npm = require("npm") -npm.load(myConfigObject, function (er) { - if (er) return handlError(er) - npm.commands.install(["some", "args"], function (er, data) { - if (er) return commandFailed(er) - // command succeeded, and data might have some info - }) - npm.registry.log.on("log", function (message) { .... }) -}) -``` - -The `load` function takes an object hash of the command-line configs. -The various `npm.commands.<cmd>` functions take an **array** of -positional argument **strings**. The last argument to any -`npm.commands.<cmd>` function is a callback. Some commands take other -optional arguments. Read the source. - -You cannot set configs individually for any single npm function at this -time. Since `npm` is a singleton, any call to `npm.config.set` will -change the value for *all* npm commands in that process. - -See `./bin/npm-cli.js` for an example of pulling config values off of the -command line arguments using nopt. You may also want to check out `npm -help config` to learn about all the options you can set there. - ## More Docs Check out the [docs](https://docs.npmjs.com/), |