Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:npm package tarball

From ReverseEngineering.wiki
Format
Magic 1F 8B (gzip) around tar; entries prefixed package/
Extensions .tgz
On this wiki Facts · Code · Notes · Topics

The npm registry package (.tgz): a gzipped tar whose entries all start with package/, holding package.json and the published files; the lifecycle scripts in package.json (preinstall, install, postinstall) run on the installing machine, and binding.gyp triggers a default node-gyp build.

npm pack and npm publish produce <name>-<version>.tgz. It is a gzipped tar in which every path begins with package/ and the first-level file package/package.json describes it.

How pacote writes the tarball

npm/pacote lib/util/tar-create-options.js: prefix package/, portable mode, gzip level 9, every entry's mtime forced to 1985-10-26T08:15:00Z (so timestamps in a published tarball are usually not real dates) and the executable bits added to files named in bin. Which files go in is decided by npm-packlist from the files field, .npmignore (or .gitignore when no .npmignore) and fixed always-included files (per the package.json docs, the files named in bin are among them; Unverified: README, LICENSE and the main file). When unpacking, pacote uses strip: 1 to remove the package/ prefix. Registries and lockfiles identify a tarball by its integrity value (sha512 by default in pacote, SRI format sha512-<base64>).

Lifecycle scripts: where code runs

The scripts object in package.json is the part to read first. On npm install / npm ci of a package and its dependencies the order is preinstall (before dependencies are fetched), install, postinstall, then prepublish, preprepare, prepare, postprepare. If the package root has a binding.gyp and no own install or preinstall script, npm defaults install to node-gyp rebuild; "gypfile": false turns that off. --ignore-scripts disables running them (Unverified: the exact scope of that flag for dependency scripts; read the npm config docs). Install scripts receive environment variables such as npm_package_resolved, npm_package_integrity, npm_package_optional and npm_package_json. bin entries are linked into the bin directory (a symlink on Unix, a .cmd shim on Windows).

Git dependencies run prepare before they are packed.

Code & repositories

  • https://github.com/npm/cli @ ae98c62586b6fea44114f72e249e246a2981de70 · license: Artistic-2.0 (declared by the contributor; GitHub's detector did not recognize LICENSE)
    npm CLI documentation of lifecycle scripts and package.json fields.
    Tested on: source read, not run: docs read, not run · checked 2026-10-19
  • https://github.com/npm/pacote @ c6edb334639a3f992b94ba5c032e199ff1f3ddbb · license: ISC (declared by the contributor for the files used; GitHub reports ISC (read from LICENSE; GitHub's API was busy) for the repository)
    pacote: creates and fetches npm package tarballs (package/ prefix, fixed mtime).
    Tested on: source read, not run · checked 2026-10-19

See also

Technique:Install-time code execution in package archives, Library:Electron and Format:ASAR archive (Electron) for apps built from npm packages.