Skip to content

Commit

Permalink
readme: nuke "using npm programmatically" section
Browse files Browse the repository at this point in the history
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: npm/npm#11130
Credit: @ljharb
Reviewed-By: @othiym23
  • Loading branch information
ljharb authored and iarna committed Jan 21, 2016
1 parent 382e71a commit e6d238a
Showing 1 changed file with 0 additions and 46 deletions.
46 changes: 0 additions & 46 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/),
Expand Down

0 comments on commit e6d238a

Please sign in to comment.