1NPM-DEVELOPERS(7)                                            NPM-DEVELOPERS(7)
2
3
4

NAME

6       npm-developers - Developer Guide
7

DESCRIPTION

9       So,  you've  decided  to  use npm to develop (and maybe publish/deploy)
10       your project.
11
12       Fantastic!
13
14       There are a few things that you need to do above the simple steps  that
15       your users will do to install your program.
16

About These Documents

18       These are man pages.  If you install npm, you should be able to then do
19       man npm-thing to get the documentation on a particular  topic,  or  npm
20       help thing to see the same information.
21

What is a package

23       A package is:
24
25       · a) a folder containing a program described by a package.json file
26
27       · b) a gzipped tarball containing (a)
28
29       · c) a url that resolves to (b)
30
31       · d) a <name>@<version> that is published on the registry with (c)
32
33       · e) a <name>@<tag> that points to (d)
34
35       · f) a <name> that has a "latest" tag satisfying (e)
36
37       · g) a git url that, when cloned, results in (a).
38
39
40       Even if you never publish your package, you can still get a lot of ben‐
41       efits of using npm if you just want to write a node  program  (a),  and
42       perhaps  if  you  also  want  to be able to easily install it elsewhere
43       after packing it up into a tarball (b).
44
45       Git urls can be of the form:
46
47         git://github.com/user/project.git#commit-ish
48         git+ssh://user@hostname:project.git#commit-ish
49         git+http://user@hostname/project/blah.git#commit-ish
50         git+https://user@hostname/project/blah.git#commit-ish
51
52       The commit-ish can be any tag, sha, or branch which can be supplied  as
53       an argument to git checkout.  The default is master.
54

The package.json File

56       You  need to have a package.json file in the root of your project to do
57       much of anything with npm.  That is basically the whole interface.
58
59       See npm help 5 package.json for details about what goes in  that  file.
60       At the very least, you need:
61
62       · name:  This  should be a string that identifies your project.  Please
63         do not use the name to specify  that  it  runs  on  node,  or  is  in
64         JavaScript.   You can use the "engines" field to explicitly state the
65         versions of node (or whatever else) that your program  requires,  and
66         it's pretty well assumed that it's JavaScript.  It does not necessar‐
67         ily need to match your github  repository  name.   So,  node-foo  and
68         bar-js are bad names.  foo or bar are better.
69
70       · version: A semver-compatible version.
71
72       · engines:  Specify  the  versions of node (or whatever else) that your
73         program runs on.  The node API changes a lot, and there may  be  bugs
74         or new functionality that you depend on.  Be explicit.
75
76       · author: Take some credit.
77
78       · scripts:  If  you  have a special compilation or installation script,
79         then you should put it in the scripts object.  You should  definitely
80         have at least a basic smoke-test command as the "scripts.test" field.
81         See npm help 7 scripts.
82
83       · main: If you have a single module that serves as the entry  point  to
84         your   program   (like   what   the   "foo"   package  gives  you  at
85         require("foo")), then you need to specify that in the "main" field.
86
87       · directories: This is an object mapping names to  folders.   The  best
88         ones  to include are "lib" and "doc", but if you use "man" to specify
89         a folder full of man pages, they'll get  installed  just  like  these
90         ones.
91
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  help  npm-init
95       for more info.
96

Keeping files out of your package

98       Use a .npmignore file to keep stuff out of your package.  If there's no
99       .npmignore file, but there is a .gitignore file, then npm  will  ignore
100       the stuff matched by the .gitignore file.  If you want to include some‐
101       thing that is excluded by your .gitignore file, you can create an empty
102       .npmignore  file to override it. Like git, npm looks for .npmignore and
103       .gitignore files in all subdirectories of your package,  not  only  the
104       root directory.
105
106       .npmignore      files     follow     the     same     pattern     rules
107       https://git-scm.com/book/en/v2/Git-Basics-Record
108       ing-Changes-to-the-Repository#Ignoring-Files as .gitignore files:
109
110       · Blank lines or lines starting with # are ignored.
111
112       · Standard glob patterns work.
113
114       · You can end patterns with a forward slash / to specify a directory.
115
116       · You can negate a pattern by starting it with an exclamation point !.
117
118
119       By  default,  the  following paths and files are ignored, so there's no
120       need to add them to .npmignore explicitly:
121
122       · .*.swp
123
124       · ._*
125
126       · .DS_Store
127
128       · .git
129
130       · .hg
131
132       · .npmrc
133
134       · .lock-wscript
135
136       · .svn
137
138       · .wafpickle-*
139
140       · config.gypi
141
142       · CVS
143
144       · npm-debug.log
145
146
147       Additionally, everything in node_modules is ignored, except for bundled
148       dependencies.  npm  automatically handles this for you, so don't bother
149       adding node_modules to .npmignore.
150
151       The following paths and files are never  ignored,  so  adding  them  to
152       .npmignore is pointless:
153
154       · package.json
155
156       · README (and its variants)
157
158       · CHANGELOG (and its variants)
159
160       · LICENSE / LICENCE
161
162
163       If,  given  the  structure of your project, you find .npmignore to be a
164       maintenance headache, you might instead try populating the files  prop‐
165       erty of package.json, which is an array of file or directory names that
166       should be included in your package. Sometimes a whitelist is easier  to
167       manage than a blacklist.
168
169   Testing whether your .npmignore or files config works
170       If  you  want  to  double check that your package will include only the
171       files you intend it to when published, you can run the npm pack command
172       locally  which  will  generate  a tarball in the working directory, the
173       same way it does for publishing.
174
176       npm link is designed to install  a  development  package  and  see  the
177       changes  in real time without having to keep re-installing it.  (You do
178       need to either re-link or npm rebuild -g to update  compiled  packages,
179       of course.)
180
181       More info at npm help npm-link.
182

Before Publishing: Make Sure Your Package Installs and Works

184       This is important.
185
186       If  you can not install it locally, you'll have problems trying to pub‐
187       lish it.  Or, worse yet, you'll be able to publish it,  but  you'll  be
188       publishing a broken or pointless package.  So don't do that.
189
190       In the root of your package, do this:
191
192         npm install . -g
193
194       That'll show you that it's working.  If you'd rather just create a sym‐
195       link package that points to your working directory, then do this:
196
197         npm link
198
199       Use npm ls -g to see if it's there.
200
201       To test a local install, go into some other folder, and then do:
202
203         cd ../some-other-folder
204         npm install ../my-package
205
206       to install it locally into the node_modules folder in that other place.
207
208       Then go into the node-repl, and try using require("my-thing") to  bring
209       in your module's main module.
210

Create a User Account

212       Create a user with the adduser command.  It works like this:
213
214         npm adduser
215
216       and then follow the prompts.
217
218       This is documented better in npm help adduser.
219

Publish your package

221       This part's easy.  In the root of your folder, do this:
222
223         npm publish
224
225       You can give publish a url to a tarball, or a filename of a tarball, or
226       a path to a folder.
227
228       Note that pretty much everything in that  folder  will  be  exposed  by
229       default.   So, if you have secret stuff in there, use a .npmignore file
230       to list out the globs to ignore, or publish from a fresh checkout.
231

Brag about it

233       Send emails, write blogs, blab in IRC.
234
235       Tell the world how easy it is to install your program!
236

SEE ALSO

238       · npm help npm
239
240       · npm help init
241
242       · npm help 5 package.json
243
244       · npm help 7 scripts
245
246       · npm help publish
247
248       · npm help adduser
249
250       · npm help 7 registry
251
252
253
254
255
256                                  April 2019                 NPM-DEVELOPERS(7)
Impressum