npm-pack

Create a tarball from the current package in the current directory

$ npm pack

$ npm pack [path/to/package_directory]

$ npm pack --dry-run

$ npm pack --ignore-scripts

$ npm pack --registry [https://registry.npmjs.org/]

npm pack [--json] [--dry-run] [--pack-destination <dir>] [<package-spec>...]

<package-spec>
    An optional argument specifying the package to pack. This can be a folder path, a tarball file, a package name (@scope/name), a name and version (name@version), or a git URL. If omitted, npm pack will pack the package in the current working directory.

--dry-run
    Performs all actions without actually creating the tarball. It shows which files would be included in the package without writing the .tgz file to disk. Useful for verification.

--json
    Outputs data about the created tarball(s) as a JSON array to stdout. This is useful for programmatic consumption, providing details like the filename, size, and shasum of the generated archive.

--pack-destination <dir>
    Specifies the directory where the generated tarball(s) should be saved. By default, tarballs are saved to the current working directory.

The npm pack command creates a gzipped tarball (.tgz) of the current or specified package. This tarball contains all the files that would be included if the package were published to the npm registry, respecting the files field in package.json and .npmignore rules (which work similarly to .gitignore).

It's primarily used for testing a package locally before publishing it, sharing a package with others without pushing it to a registry, or for creating offline installations. When run in a package directory without arguments, it packs the current directory. If a package specifier is provided, it fetches and packs that package from the registry. Internally, npm publish calls npm pack to generate the tarball before uploading it.

The resulting .tgz file will be placed in the current working directory by default, but this can be changed using the --pack-destination option. This command is a crucial tool for developers to inspect and verify the publishable artifact.

When packing a local directory, npm pack runs the prepack script hook and does not run the prepublish script (which has been largely superseded by prepare and prepack in modern npm). Files ignored by .npmignore (or .gitignore if no .npmignore exists) and those not explicitly included via the files array in package.json will be excluded from the tarball, which is critical for minimizing package size. Be mindful of large files or directories that could inadvertently be included.

npm pack specifically triggers the prepack and postpack lifecycle scripts defined in your package.json. The prepack script runs before the tarball is created, allowing you to perform build steps or other preparations. The postpack script runs after the tarball has been successfully created. This provides hooks for automating tasks related to the packing process.

The contents of the generated tarball are determined by several factors:
1. The files array in package.json explicitly lists files/directories to include.
2. A .npmignore file (if present) specifies patterns of files/directories to exclude.
3. If no .npmignore exists, .gitignore is used instead, but only for files not explicitly listed in files.
4. Certain common files are always excluded (e.g., .git/, node_modules/, npm-debug.log, etc.) unless explicitly included by the files array.
Understanding these rules is crucial for creating correctly sized and structured packages.

The npm pack command has been a fundamental part of the npm CLI since its early days, serving as the core mechanism for bundling package files into a distributable tarball. Its evolution is closely tied to the publishing workflow. Notably, the behavior surrounding script hooks (like prepublish, prepare, and prepack) has been refined over npm versions to provide clearer semantics for when scripts run during different lifecycle stages, with prepack specifically designed for the packing operation.

npm publish(1), npm install(1), npm link(1), npm prune(1)