org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/doc/misc/npm-developers.md

   1 npm-developers(7) -- Developer Guide
   2 ====================================
   3
   4 ## DESCRIPTION
   5
   6 So, you've decided to use npm to develop (and maybe publish/deploy)
   7 your project.
   8
   9 Fantastic!
  10
  11 There are a few things that you need to do above the simple steps
  12 that your users will do to install your program.
  13
  14 ## About These Documents
  15
  16 These are man pages.  If you install npm, you should be able to
  17 then do `man npm-thing` to get the documentation on a particular
  18 topic, or `npm help thing` to see the same information.
  19
  20 ## What is a `package`
  21
  22 A package is:
  23
  24 * a) a folder containing a program described by a package.json file
  25 * b) a gzipped tarball containing (a)
  26 * c) a url that resolves to (b)
  27 * d) a `<name>@<version>` that is published on the registry with (c)
  28 * e) a `<name>@<tag>` that points to (d)
  29 * f) a `<name>` that has a "latest" tag satisfying (e)
  30 * g) a `git` url that, when cloned, results in (a).
  31
  32 Even if you never publish your package, you can still get a lot of
  33 benefits of using npm if you just want to write a node program (a), and
  34 perhaps if you also want to be able to easily install it elsewhere
  35 after packing it up into a tarball (b).
  36
  37 Git urls can be of the form:
  38
  39     git://github.com/user/project.git#commit-ish
  40     git+ssh://user@hostname:project.git#commit-ish
  41     git+http://user@hostname/project/blah.git#commit-ish
  42     git+https://user@hostname/project/blah.git#commit-ish
  43
  44 The `commit-ish` can be any tag, sha, or branch which can be supplied as
  45 an argument to `git checkout`.  The default is `master`.
  46
  47 ## The package.json File
  48
  49 You need to have a `package.json` file in the root of your project to do
  50 much of anything with npm.  That is basically the whole interface.
  51
  52 See `package.json(5)` for details about what goes in that file.  At the very
  53 least, you need:
  54
  55 * name:
  56   This should be a string that identifies your project.  Please do not
  57   use the name to specify that it runs on node, or is in JavaScript.
  58   You can use the "engines" field to explicitly state the versions of
  59   node (or whatever else) that your program requires, and it's pretty
  60   well assumed that it's javascript.
  61
  62   It does not necessarily need to match your github repository name.
  63
  64   So, `node-foo` and `bar-js` are bad names.  `foo` or `bar` are better.
  65
  66 * version:
  67   A semver-compatible version.
  68
  69 * engines:
  70   Specify the versions of node (or whatever else) that your program
  71   runs on.  The node API changes a lot, and there may be bugs or new
  72   functionality that you depend on.  Be explicit.
  73
  74 * author:
  75   Take some credit.
  76
  77 * scripts:
  78   If you have a special compilation or installation script, then you
  79   should put it in the `scripts` object.  You should definitely have at
  80   least a basic smoke-test command as the "scripts.test" field.
  81   See npm-scripts(7).
  82
  83 * main:
  84   If you have a single module that serves as the entry point to your
  85   program (like what the "foo" package gives you at require("foo")),
  86   then you need to specify that in the "main" field.
  87
  88 * directories:
  89   This is an object mapping names to folders.  The best ones to include are
  90   "lib" and "doc", but if you use "man" to specify a folder full of man pages,
  91   they'll get installed just like these ones.
  92
  93 You can use `npm init` in the root of your package in order to get you
  94 started with a pretty basic package.json file.  See `npm-init(1)` for
  95 more info.
  96
  97 ## Keeping files *out* of your package
  98
  99 Use a `.npmignore` file to keep stuff out of your package.  If there's
 100 no `.npmignore` file, but there *is* a `.gitignore` file, then npm will
 101 ignore the stuff matched by the `.gitignore` file.  If you *want* to
 102 include something that is excluded by your `.gitignore` file, you can
 103 create an empty `.npmignore` file to override it. Like `git`, `npm` looks
 104 for `.npmignore` and `.gitignore` files in all subdirectories of your
 105 package, not only the root directory.
 106
 107 `.npmignore` files follow the [same pattern rules](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#Ignoring-Files)
 108 as `.gitignore` files:
 109
 110 * Blank lines or lines starting with `#` are ignored.
 111 * Standard glob patterns work.
 112 * You can end patterns with a forward slash `/` to specify a directory.
 113 * You can negate a pattern by starting it with an exclamation point `!`.
 114
 115 By default, the following paths and files are ignored, so there's no
 116 need to add them to `.npmignore` explicitly:
 117
 118 * `.*.swp`
 119 * `._*`
 120 * `.DS_Store`
 121 * `.git`
 122 * `.hg`
 123 * `.npmrc`
 124 * `.lock-wscript`
 125 * `.svn`
 126 * `.wafpickle-*`
 127 * `config.gypi`
 128 * `CVS`
 129 * `npm-debug.log`
 130
 131 Additionally, everything in `node_modules` is ignored, except for
 132 bundled dependencies. npm automatically handles this for you, so don't
 133 bother adding `node_modules` to `.npmignore`.
 134
 135 The following paths and files are never ignored, so adding them to
 136 `.npmignore` is pointless:
 137
 138 * `package.json`
 139 * `README` (and its variants)
 140 * `CHANGELOG` (and its variants)
 141 * `LICENSE` / `LICENCE`
 142
 143 ## Link Packages
 144
 145 `npm link` is designed to install a development package and see the
 146 changes in real time without having to keep re-installing it.  (You do
 147 need to either re-link or `npm rebuild -g` to update compiled packages,
 148 of course.)
 149
 150 More info at `npm-link(1)`.
 151
 152 ## Before Publishing: Make Sure Your Package Installs and Works
 153
 154 **This is important.**
 155
 156 If you can not install it locally, you'll have
 157 problems trying to publish it.  Or, worse yet, you'll be able to
 158 publish it, but you'll be publishing a broken or pointless package.
 159 So don't do that.
 160
 161 In the root of your package, do this:
 162
 163     npm install . -g
 164
 165 That'll show you that it's working.  If you'd rather just create a symlink
 166 package that points to your working directory, then do this:
 167
 168     npm link
 169
 170 Use `npm ls -g` to see if it's there.
 171
 172 To test a local install, go into some other folder, and then do:
 173
 174     cd ../some-other-folder
 175     npm install ../my-package
 176
 177 to install it locally into the node_modules folder in that other place.
 178
 179 Then go into the node-repl, and try using require("my-thing") to
 180 bring in your module's main module.
 181
 182 ## Create a User Account
 183
 184 Create a user with the adduser command.  It works like this:
 185
 186     npm adduser
 187
 188 and then follow the prompts.
 189
 190 This is documented better in npm-adduser(1).
 191
 192 ## Publish your package
 193
 194 This part's easy.  In the root of your folder, do this:
 195
 196     npm publish
 197
 198 You can give publish a url to a tarball, or a filename of a tarball,
 199 or a path to a folder.
 200
 201 Note that pretty much **everything in that folder will be exposed**
 202 by default.  So, if you have secret stuff in there, use a
 203 `.npmignore` file to list out the globs to ignore, or publish
 204 from a fresh checkout.
 205
 206 ## Brag about it
 207
 208 Send emails, write blogs, blab in IRC.
 209
 210 Tell the world how easy it is to install your program!
 211
 212 ## SEE ALSO
 213
 214 * npm-faq(7)
 215 * npm(1)
 216 * npm-init(1)
 217 * package.json(5)
 218 * npm-scripts(7)
 219 * npm-publish(1)
 220 * npm-adduser(1)
 221 * npm-registry(7)