README.md
1# npm-packlist
2
3[](https://travis-ci.com/npm/npm-packlist)
4
5Get a list of the files to add from a folder into an npm package
6
7These can be handed to [tar](http://npm.im/tar) like so to make an npm
8package tarball:
9
10```js
11const packlist = require('npm-packlist')
12const tar = require('tar')
13const packageDir = '/path/to/package'
14const packageTarball = '/path/to/package.tgz'
15
16packlist({ path: packageDir })
17 .then(files => tar.create({
18 prefix: 'package/',
19 cwd: packageDir,
20 file: packageTarball,
21 gzip: true
22 }, files))
23 .then(_ => {
24 // tarball has been created, continue with your day
25 })
26```
27
28This uses the following rules:
29
301. If a `package.json` file is found, and it has a `files` list,
31 then ignore everything that isn't in `files`. Always include the
32 readme, license, notice, changes, changelog, and history files, if
33 they exist, and the package.json file itself.
342. If there's no `package.json` file (or it has no `files` list), and
35 there is a `.npmignore` file, then ignore all the files in the
36 `.npmignore` file.
373. If there's no `package.json` with a `files` list, and there's no
38 `.npmignore` file, but there is a `.gitignore` file, then ignore
39 all the files in the `.gitignore` file.
404. Everything in the root `node_modules` is ignored, unless it's a
41 bundled dependency. If it IS a bundled dependency, and it's a
42 symbolic link, then the target of the link is included, not the
43 symlink itself.
444. Unless they're explicitly included (by being in a `files` list, or
45 a `!negated` rule in a relevant `.npmignore` or `.gitignore`),
46 always ignore certain common cruft files:
47
48 1. .npmignore and .gitignore files (their effect is in the package
49 already, there's no need to include them in the package)
50 2. editor junk like `.*.swp`, `._*` and `.*.orig` files
51 3. `.npmrc` files (these may contain private configs)
52 4. The `node_modules/.bin` folder
53 5. Waf and gyp cruft like `/build/config.gypi` and `.lock-wscript`
54 6. Darwin's `.DS_Store` files because wtf are those even
55 7. `npm-debug.log` files at the root of a project
56
57 You can explicitly re-include any of these with a `files` list in
58 `package.json` or a negated ignore file rule.
59
60## API
61
62Same API as [ignore-walk](http://npm.im/ignore-walk), just hard-coded
63file list and rule sets.
64
65The `Walker` and `WalkerSync` classes take a `bundled` argument, which
66is a list of package names to include from node_modules. When calling
67the top-level `packlist()` and `packlist.sync()` functions, this
68module calls into `npm-bundled` directly.
69
){kind=link}