npm pack: include required runtime helper files

Compare checkout files with package contents

Find the missing module in the installed-package stack and compare it with the package file list. An install can succeed without executing every runtime path, so missing helpers may appear only when consumers load the package.

The test entry file required ./dist/formatter.cjs. Both files existed in the source checkout, but the files list included only index.cjs. The installed package therefore lacked the helper that the entry file expected.

Inspect packing without publishing

Run pack in dry-run mode to inspect the selected files. The --ignore-scripts option keeps lifecycle execution out of this inspection; if the real release depends on an approved preparation step, verify that step separately.

npm includes the file named by main under its documented packing rules. This reproduction deliberately tests a non-entry helper so it does not incorrectly assume that excluding main through files alone removes it.

sh · EXAMPLE

npm pack --dry-run --json --ignore-scripts

Include the required runtime directory deliberately

The corrected fixture metadata below keeps its entry file and explicitly includes dist. It is synthetic local package metadata, not a public package you should install.

Inspect which files that directory actually contains before publishing. Broadening a file list can accidentally include unrelated build outputs or private data. Choose the intended runtime distribution, not every file in the repository.

json · EXAMPLE

{
  "name": "fixture-packed",
  "version": "1.0.0",
  "main": "index.cjs",
  "files": ["index.cjs", "dist"]
}

Create and test the actual tarball

After the intended build output exists, create a local tarball and install that artifact into a disposable consumer through the normal package-install process. This is different from linking or requiring the source checkout.

The local corrected tarball included dist/formatter.cjs and the consumer loaded packed helper loaded. The failed tarball installed successfully too, which is why the runtime import was a necessary verification step.

sh · EXAMPLE

# Creates a local .tgz; does not publish to the registry.
npm pack --ignore-scripts

Keep the release artifact as the verification target

Check the dry-run and actual packed files after the production build and approved release preparation. Review ignore files, files rules, entry declarations, and generated helpers together when the result differs from expectations.

If this fixes a package already published to a registry, use its normal new-version release process. Our same-version local tarballs were isolated test artifacts, not a recommendation to replace published versions in place. Verify consumers against the corrected distribution before release.

Know the limits

Reproduced with npm 12.2.1 and Node.js 24.22.1 in a disposable Linux container using local fixtures, with external networking disabled during tests. The fixture’s main file was packed, but its required dist/formatter.cjs was excluded. Installation succeeded and requiring the package failed. Including dist repaired the tarball and consumer load. No package was published; registry distribution and build lifecycle hooks were not tested.

Sources & further reading

A technical publication by CoreTrailKit.

Browse all articles