[6a3a178] | 1 | # npm-packlist
|
---|
| 2 |
|
---|
| 3 | [![Build Status](https://travis-ci.com/npm/npm-packlist.svg?token=hHeDp9pQmz9kvsgRNVHy&branch=master)](https://travis-ci.com/npm/npm-packlist)
|
---|
| 4 |
|
---|
| 5 | Get a list of the files to add from a folder into an npm package.
|
---|
| 6 |
|
---|
| 7 | These can be handed to [tar](http://npm.im/tar) like so to make an npm
|
---|
| 8 | package tarball:
|
---|
| 9 |
|
---|
| 10 | ```js
|
---|
| 11 | const packlist = require('npm-packlist')
|
---|
| 12 | const tar = require('tar')
|
---|
| 13 | const packageDir = '/path/to/package'
|
---|
| 14 | const packageTarball = '/path/to/package.tgz'
|
---|
| 15 |
|
---|
| 16 | packlist({ 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 |
|
---|
| 28 | This uses the following rules:
|
---|
| 29 |
|
---|
| 30 | 1. 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.
|
---|
| 34 | 2. 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.
|
---|
| 37 | 3. 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.
|
---|
| 40 | 4. 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.
|
---|
| 44 | 4. 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 | Only the `package.json` file in the very root of the project is ever
|
---|
| 61 | inspected for a `files` list. Below the top level of the root package,
|
---|
| 62 | `package.json` is treated as just another file, and no package-specific
|
---|
| 63 | semantics are applied.
|
---|
| 64 |
|
---|
| 65 | ### Interaction between `package.json` and `.npmignore` rules
|
---|
| 66 |
|
---|
| 67 | For simplicity, it is best to use _either_ a `files` list in `package.json`
|
---|
| 68 | _or_ a `.npmignore` file, and not both. If you only use one of these
|
---|
| 69 | methods, you can skip this documentation section.
|
---|
| 70 |
|
---|
| 71 | The `files` list in `package.json` is used to direct the exploration of the
|
---|
| 72 | tree. In other words, that's all the walker will ever look at when
|
---|
| 73 | exploring that level.
|
---|
| 74 |
|
---|
| 75 | In some cases this can lead to a `.npmignore` file being ignored. If a
|
---|
| 76 | _directory_ is listed in `files`, then any rules in a root or nested
|
---|
| 77 | `.npmignore` files will be honored.
|
---|
| 78 |
|
---|
| 79 | For example, with this package.json:
|
---|
| 80 |
|
---|
| 81 | ```json
|
---|
| 82 | {
|
---|
| 83 | "files": [ "dir" ]
|
---|
| 84 | }
|
---|
| 85 | ```
|
---|
| 86 |
|
---|
| 87 | a `.npmignore` file at `dir/.npmignore` (and any subsequent
|
---|
| 88 | sub-directories) will be honored. However, a `.npmignore` at the root
|
---|
| 89 | level will be skipped.
|
---|
| 90 |
|
---|
| 91 | Conversely, with this package.json:
|
---|
| 92 |
|
---|
| 93 | ```
|
---|
| 94 | {
|
---|
| 95 | "files": ["dir/subdir"]
|
---|
| 96 | }
|
---|
| 97 | ```
|
---|
| 98 |
|
---|
| 99 | a `.npmignore` file at `dir/.npmignore` will not be honored.
|
---|
| 100 |
|
---|
| 101 | Any specific file matched by a glob or filename in the package.json `files`
|
---|
| 102 | list will be included, and cannot be excluded by any `.npmignore` files in
|
---|
| 103 | nested directories, or by a `.npmignore` file in the root package
|
---|
| 104 | directory, unless that root `.npmignore` file is also in the `files` list.
|
---|
| 105 |
|
---|
| 106 | The previous (v1) implementation used in npm 6 and below treated
|
---|
| 107 | `package.json` as a special sort of "reverse ignore" file. That is, it was
|
---|
| 108 | parsed and handled as if it was a `.npmignore` file with `!` prepended to
|
---|
| 109 | all of the globs in the `files` list. In order to include children of a
|
---|
| 110 | directory listed in `files`, they would _also_ have `/**` appended to them.
|
---|
| 111 |
|
---|
| 112 | This is tricky to explain, but is a significant improvement over the
|
---|
| 113 | previous (v1) implementation used in npm 6 and below, with the following
|
---|
| 114 | beneficial properties:
|
---|
| 115 |
|
---|
| 116 | - If you have `{"files":["lib"]}` in `package.json`, then the walker will
|
---|
| 117 | still ignore files such as `lib/.DS_Store` and `lib/.foo.swp`. The
|
---|
| 118 | previous implementation would include these files, as they'd be matched
|
---|
| 119 | by the computed `!lib/**` ignore rule.
|
---|
| 120 | - If you have `{"files":["lib/a.js","lib/b.js"]}` in `package.json`, and a
|
---|
| 121 | `lib/.npmignore` containing `a.js`, then the walker will still include
|
---|
| 122 | the two files indicated in `package.json`, and ignore the
|
---|
| 123 | `lib/.npmignore` file. The previous implementation would mark these
|
---|
| 124 | files for inclusion, but then _exclude_ them when it came to the nested
|
---|
| 125 | `.npmignore` file. (Ignore file semantics dictate that a "closer" ignore
|
---|
| 126 | file always takes precedence.)
|
---|
| 127 | - A file in `lib/pkg-template/package.json` will be included, and its
|
---|
| 128 | `files` list will not have any bearing on other files being included or
|
---|
| 129 | skipped. When treating `package.json` as just Yet Another ignore file,
|
---|
| 130 | this was not the case, leading to difficulty for modules that aim to
|
---|
| 131 | initialize a project.
|
---|
| 132 |
|
---|
| 133 | In general, this walk should work as a reasonable developer would expect.
|
---|
| 134 | Matching human expectation is tricky business, and if you find cases where
|
---|
| 135 | it violates those expectations, [please let us
|
---|
| 136 | know](https://github.com/npm/npm-packlist/issues).
|
---|
| 137 |
|
---|
| 138 | ## API
|
---|
| 139 |
|
---|
| 140 | Same API as [ignore-walk](http://npm.im/ignore-walk), just hard-coded
|
---|
| 141 | file list and rule sets.
|
---|
| 142 |
|
---|
| 143 | The `Walker` and `WalkerSync` classes take a `bundled` argument, which
|
---|
| 144 | is a list of package names to include from node_modules. When calling
|
---|
| 145 | the top-level `packlist()` and `packlist.sync()` functions, this
|
---|
| 146 | module calls into `npm-bundled` directly.
|
---|