What is npm-packlist?
The npm-packlist package is used to generate a list of files that would be included in an npm package publish. This includes filtering out files that are not meant to be published, such as those specified in `.npmignore` or the `.gitignore` files, and including those specified in the `files` array in `package.json`. It's useful for package authors to understand and control what gets included in their published npm package.
What are npm-packlist's main functionalities?
Generate packlist
This feature allows you to generate a list of files that would be included if you were to publish the current package. The code sample demonstrates how to use npm-packlist to get an array of file paths that are included in the package's publish list.
const packlist = require('npm-packlist');
packlist().then(files => {
console.log(files)
});
Customize packlist with package.json
While not a direct feature of npm-packlist, the package respects the `files` field in `package.json`. This allows users to explicitly specify which files or directories should be included in the publish. The code sample shows how to specify a list of files and directories in `package.json` that should be included in the npm package.
{
"files": [
"lib/**/*",
"bin/*",
"README.md"
]
}
Other packages similar to npm-packlist
glob
The 'glob' package provides functionality to match files using the patterns the shell uses, like stars and stuff. It's similar to npm-packlist in that it can be used to select files to include in a package, but it does not directly integrate with npm's packaging logic or respect `.npmignore` and `files` in `package.json`.
ignore
The 'ignore' package is used to filter file paths according to the rules found in `.gitignore` and `.npmignore` files. It's similar to npm-packlist in its purpose of filtering out files, but it's more focused on the ignore rules and doesn't directly generate a list of files for npm packaging.
npm-packlist
Get a list of the files to add from a folder into an npm package
These can be handed to tar like so to make an npm
package tarball:
const packlist = require('npm-packlist')
const tar = require('tar')
const packageDir = '/path/to/package'
const packageTarball = '/path/to/package.tgz'
packlist({ path: packageDir })
.then(files => tar.create({
prefix: 'package/',
cwd: packageDir,
file: packageTarball,
gzip: true
}, files))
.then(_ => {
})
This uses the following rules:
-
If a package.json
file is found, and it has a files
list,
then ignore everything that isn't in files
. Always include the
readme, license, notice, changes, changelog, and history files, if
they exist, and the package.json file itself.
-
If there's no package.json
file (or it has no files
list), and
there is a .npmignore
file, then ignore all the files in the
.npmignore
file.
-
If there's no package.json
with a files
list, and there's no
.npmignore
file, but there is a .gitignore
file, then ignore
all the files in the .gitignore
file.
-
Everything in the root node_modules
is ignored, unless it's a
bundled dependency. If it IS a bundled dependency, and it's a
symbolic link, then the target of the link is included, not the
symlink itself.
-
Unless they're explicitly included (by being in a files
list, or
a !negated
rule in a relevant .npmignore
or .gitignore
),
always ignore certain common cruft files:
- .npmignore and .gitignore files (their effect is in the package
already, there's no need to include them in the package)
- editor junk like
.*.swp
, ._*
and .*.orig
files - A
/test/
or /tests/
folder at the root .npmrc
files (these may contain private configs)- The
node_modules/.bin
folder - Waf and gyp cruft like
/build/config.gypi
and .lock-wscript
- Darwin's
.DS_Store
files because wtf are those even npm-debug.log
files at the root of a project
You can explicitly re-include any of these with a files
list in
package.json
or a negated ignore file rule.
API
Same API as ignore-walk, just hard-coded
file list and rule sets.
The Walker
and WalkerSync
classes take a bundled
argument, which
is a list of package names to include from node_modules. When calling
the top-level packlist()
and packlist.sync()
functions, this
module calls into npm-bundled
directly.