diff options
Diffstat (limited to 'deps/node/deps/npm/doc/misc/npm-developers.md')
| -rw-r--r-- | deps/node/deps/npm/doc/misc/npm-developers.md | 233 |
1 files changed, 0 insertions, 233 deletions
diff --git a/deps/node/deps/npm/doc/misc/npm-developers.md b/deps/node/deps/npm/doc/misc/npm-developers.md deleted file mode 100644 index 55c8d9b0..00000000 --- a/deps/node/deps/npm/doc/misc/npm-developers.md +++ /dev/null @@ -1,233 +0,0 @@ -npm-developers(7) -- Developer Guide -==================================== - -## DESCRIPTION - -So, you've decided to use npm to develop (and maybe publish/deploy) -your project. - -Fantastic! - -There are a few things that you need to do above the simple steps -that your users will do to install your program. - -## About These Documents - -These are man pages. If you install npm, you should be able to -then do `man npm-thing` to get the documentation on a particular -topic, or `npm help thing` to see the same information. - -## What is a `package` - -A package is: - -* a) a folder containing a program described by a package.json file -* b) a gzipped tarball containing (a) -* c) a url that resolves to (b) -* d) a `<name>@<version>` that is published on the registry with (c) -* e) a `<name>@<tag>` that points to (d) -* f) a `<name>` that has a "latest" tag satisfying (e) -* g) a `git` url that, when cloned, results in (a). - -Even if you never publish your package, you can still get a lot of -benefits of using npm if you just want to write a node program (a), and -perhaps if you also want to be able to easily install it elsewhere -after packing it up into a tarball (b). - -Git urls can be of the form: - - git://github.com/user/project.git#commit-ish - git+ssh://user@hostname:project.git#commit-ish - git+http://user@hostname/project/blah.git#commit-ish - git+https://user@hostname/project/blah.git#commit-ish - -The `commit-ish` can be any tag, sha, or branch which can be supplied as -an argument to `git checkout`. The default is `master`. - -## The package.json File - -You need to have a `package.json` file in the root of your project to do -much of anything with npm. That is basically the whole interface. - -See `package.json(5)` for details about what goes in that file. At the very -least, you need: - -* name: - This should be a string that identifies your project. Please do not - use the name to specify that it runs on node, or is in JavaScript. - You can use the "engines" field to explicitly state the versions of - node (or whatever else) that your program requires, and it's pretty - well assumed that it's JavaScript. - - It does not necessarily need to match your github repository name. - - So, `node-foo` and `bar-js` are bad names. `foo` or `bar` are better. - -* version: - A semver-compatible version. - -* engines: - Specify the versions of node (or whatever else) that your program - runs on. The node API changes a lot, and there may be bugs or new - functionality that you depend on. Be explicit. - -* author: - Take some credit. - -* scripts: - If you have a special compilation or installation script, then you - should put it in the `scripts` object. You should definitely have at - least a basic smoke-test command as the "scripts.test" field. - See npm-scripts(7). - -* main: - If you have a single module that serves as the entry point to your - program (like what the "foo" package gives you at require("foo")), - then you need to specify that in the "main" field. - -* directories: - This is an object mapping names to folders. The best ones to include are - "lib" and "doc", but if you use "man" to specify a folder full of man pages, - they'll get installed just like these ones. - -You can use `npm init` in the root of your package in order to get you -started with a pretty basic package.json file. See `npm-init(1)` for -more info. - -## Keeping files *out* of your package - -Use a `.npmignore` file to keep stuff out of your package. If there's -no `.npmignore` file, but there *is* a `.gitignore` file, then npm will -ignore the stuff matched by the `.gitignore` file. If you *want* to -include something that is excluded by your `.gitignore` file, you can -create an empty `.npmignore` file to override it. Like `git`, `npm` looks -for `.npmignore` and `.gitignore` files in all subdirectories of your -package, not only the root directory. - -`.npmignore` files follow the [same pattern rules](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#Ignoring-Files) -as `.gitignore` files: - -* Blank lines or lines starting with `#` are ignored. -* Standard glob patterns work. -* You can end patterns with a forward slash `/` to specify a directory. -* You can negate a pattern by starting it with an exclamation point `!`. - -By default, the following paths and files are ignored, so there's no -need to add them to `.npmignore` explicitly: - -* `.*.swp` -* `._*` -* `.DS_Store` -* `.git` -* `.hg` -* `.npmrc` -* `.lock-wscript` -* `.svn` -* `.wafpickle-*` -* `config.gypi` -* `CVS` -* `npm-debug.log` - -Additionally, everything in `node_modules` is ignored, except for -bundled dependencies. npm automatically handles this for you, so don't -bother adding `node_modules` to `.npmignore`. - -The following paths and files are never ignored, so adding them to -`.npmignore` is pointless: - -* `package.json` -* `README` (and its variants) -* `CHANGELOG` (and its variants) -* `LICENSE` / `LICENCE` - -If, given the structure of your project, you find `.npmignore` to be a -maintenance headache, you might instead try populating the `files` -property of `package.json`, which is an array of file or directory names -that should be included in your package. Sometimes a whitelist is easier -to manage than a blacklist. - -### Testing whether your `.npmignore` or `files` config works - -If you want to double check that your package will include only the files -you intend it to when published, you can run the `npm pack` command locally -which will generate a tarball in the working directory, the same way it -does for publishing. - -## Link Packages - -`npm link` is designed to install a development package and see the -changes in real time without having to keep re-installing it. (You do -need to either re-link or `npm rebuild -g` to update compiled packages, -of course.) - -More info at `npm-link(1)`. - -## Before Publishing: Make Sure Your Package Installs and Works - -**This is important.** - -If you can not install it locally, you'll have -problems trying to publish it. Or, worse yet, you'll be able to -publish it, but you'll be publishing a broken or pointless package. -So don't do that. - -In the root of your package, do this: - - npm install . -g - -That'll show you that it's working. If you'd rather just create a symlink -package that points to your working directory, then do this: - - npm link - -Use `npm ls -g` to see if it's there. - -To test a local install, go into some other folder, and then do: - - cd ../some-other-folder - npm install ../my-package - -to install it locally into the node_modules folder in that other place. - -Then go into the node-repl, and try using require("my-thing") to -bring in your module's main module. - -## Create a User Account - -Create a user with the adduser command. It works like this: - - npm adduser - -and then follow the prompts. - -This is documented better in npm-adduser(1). - -## Publish your package - -This part's easy. In the root of your folder, do this: - - npm publish - -You can give publish a url to a tarball, or a filename of a tarball, -or a path to a folder. - -Note that pretty much **everything in that folder will be exposed** -by default. So, if you have secret stuff in there, use a -`.npmignore` file to list out the globs to ignore, or publish -from a fresh checkout. - -## Brag about it - -Send emails, write blogs, blab in IRC. - -Tell the world how easy it is to install your program! - -## SEE ALSO - -* npm(1) -* npm-init(1) -* package.json(5) -* npm-scripts(7) -* npm-publish(1) -* npm-adduser(1) -* npm-registry(7) |