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

NAME

6       developers - Developer Guide
7
8   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
17   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
22   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 af‐
43       ter 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 whatever the repository
54       uses as its default branch.
55
56   The package.json File
57       You need to have a package.json file in the root of your project to  do
58       much of anything with npm.  That is basically the whole interface.
59
60       See npm help package.json for details about what goes in that file.  At
61       the very least, you need:
62
63       • name: This should be a string that identifies your  project.   Please
64         do  not  use the name to specify that it runs on node, or is in Java‐
65         Script.  You can use the "engines" field to explicitly state the ver‐
66         sions of node (or whatever else) that your program requires, and it's
67         pretty well assumed that it's JavaScript.  It  does  not  necessarily
68         need  to  match your github repository name.  So, node-foo and bar-js
69         are bad names.  foo or bar are better.
70
71       • version: A semver-compatible version.
72
73       • engines: Specify the versions of node (or whatever  else)  that  your
74         program  runs  on.  The node API changes a lot, and there may be bugs
75         or new functionality that you depend on.  Be explicit.
76
77       • author: Take some credit.
78
79       • scripts: If you have a special compilation  or  installation  script,
80         then  you should put it in the scripts object.  You should definitely
81         have at least a basic smoke-test command as the "scripts.test" field.
82         See npm help scripts.
83
84       • main:  If  you have a single module that serves as the entry point to
85         your  program  (like  what  the  "foo"  package  gives  you  at   re‐
86         quire("foo")), then you need to specify that in the "main" field.
87
88       • directories:  This  is  an object mapping names to folders.  The best
89         ones to include are "lib" and "doc", but if you use "man" to  specify
90         a  folder  full  of  man pages, they'll get installed just like these
91         ones.
92
93
94       You can use npm init in the root of your package in order  to  get  you
95       started  with  a pretty basic package.json file.  See npm help npm init
96       for more info.
97
98   Keeping files out of your Package
99       Use a .npmignore file to keep stuff out of your package.  If there's no
100       .npmignore  file,  but there is a .gitignore file, then npm will ignore
101       the stuff matched by the .gitignore file.  If you want to include some‐
102       thing that is excluded by your .gitignore file, you can create an empty
103       .npmignore file to override it. Like git, npm looks for .npmignore  and
104       .gitignore  files  in  all subdirectories of your package, not only the
105       root directory.
106
107       .npmignore     files     follow     the     same     pattern      rules
108       https://git-scm.com/book/en/v2/Git-Basics-Record
109       ing-Changes-to-the-Repository#_ignoring as .gitignore files:
110
111       • Blank lines or lines starting with # are ignored.
112
113       • Standard glob patterns work.
114
115       • You can end patterns with a forward slash / to specify a directory.
116
117       • You can negate a pattern by starting it with an exclamation point !.
118
119
120       By default, the following paths and files are ignored,  so  there's  no
121       need to add them to .npmignore explicitly:
122
123.*.swp
124
125._*
126
127.DS_Store
128
129.git
130
131.gitignore
132
133.hg
134
135.npmignore
136
137.npmrc
138
139.lock-wscript
140
141.svn
142
143.wafpickle-*
144
145config.gypi
146
147CVS
148
149npm-debug.log
150
151
152       Additionally, everything in node_modules is ignored, except for bundled
153       dependencies. npm automatically handles this for you, so  don't  bother
154       adding node_modules to .npmignore.
155
156       The  following  paths  and  files  are never ignored, so adding them to
157       .npmignore is pointless:
158
159package.json
160
161README (and its variants)
162
163CHANGELOG (and its variants)
164
165LICENSE / LICENCE
166
167
168       If, given the structure of your project, you find .npmignore  to  be  a
169       maintenance  headache, you might instead try populating the files prop‐
170       erty of package.json, which is an array of file or directory names that
171       should  be  included  in your package. Sometimes manually picking which
172       items to allow is easier to manage than building a block list.
173
174   Testing whether your .npmignore or files config works
175       If you want to double check that your package  will  include  only  the
176       files you intend it to when published, you can run the npm pack command
177       locally which will generate a tarball in  the  working  directory,  the
178       same way it does for publishing.
179
180   Link Packages
181       npm  link  is  designed  to  install  a development package and see the
182       changes in real time without having to keep re-installing it.  (You  do
183       need  to  either re-link or npm rebuild -g to update compiled packages,
184       of course.)
185
186       More info at npm help link.
187
188   Before Publishing: Make Sure Your Package Installs and Works
189       This is important.
190
191       If you can not install it locally, you'll have problems trying to  pub‐
192       lish  it.   Or,  worse yet, you'll be able to publish it, but you'll be
193       publishing a broken or pointless package.  So don't do that.
194
195       In the root of your package, do this:
196
197         npm install . -g
198
199       That'll show you that it's working.  If you'd rather just create a sym‐
200       link package that points to your working directory, then do this:
201
202         npm link
203
204       Use npm ls -g to see if it's there.
205
206       To test a local install, go into some other folder, and then do:
207
208         cd ../some-other-folder
209         npm install ../my-package
210
211       to install it locally into the node_modules folder in that other place.
212
213       Then  go into the node-repl, and try using require("my-thing") to bring
214       in your module's main module.
215
216   Create a User Account
217       Create a user with the adduser command.  It works like this:
218
219         npm adduser
220
221       and then follow the prompts.
222
223       This is documented better in npm help adduser.
224
225   Publish your Package
226       This part's easy.  In the root of your folder, do this:
227
228         npm publish
229
230       You can give publish a url to a tarball, or a filename of a tarball, or
231       a path to a folder.
232
233       Note  that pretty much everything in that folder will be exposed by de‐
234       fault.  So, if you have secret stuff in there, use a .npmignore file to
235       list out the globs to ignore, or publish from a fresh checkout.
236
237   Brag about it
238       Send emails, write blogs, blab in IRC.
239
240       Tell the world how easy it is to install your program!
241
242   See also
243       • npm help npm
244
245       • npm help init
246
247       • npm help package.json
248
249       • npm help scripts
250
251       • npm help publish
252
253       • npm help adduser
254
255       • npm help registry
256
257
258
259
260                                 January 2022                    DEVELOPERS(7)
Impressum