pnpm-airgap

The complete solution for transferring pnpm dependencies to air-gapped environments.

The Problem

Getting pnpm projects into secure, offline, or air-gapped environments is challenging:

No tooling for pnpm lockfiles - Existing airgap tools only work with npm's package-lock.json
Complex dependency trees - pnpm's advanced resolution (peer deps, optionals, workspaces) makes manual approaches nearly impossible
Registry population gap - No automated way to populate offline registries with pnpm project dependencies

The Solution

pnpm-airgap is a standalone tool that:

Reads pnpm-lock.yaml and downloads ALL dependencies
Publishes packages to any npm-compatible registry (Verdaccio, Nexus, Artifactory)
Works as a single file - no npm install required in airgap
Supports pnpm lockfile versions 5.x, 6.x, and 9.x

Quick Start

1. Download the standalone CLI

The CLI is a single file (~1.1MB) that runs with just Node.js:

# From npm (online)
npm pack pnpm-airgap
tar -xzf pnpm-airgap-*.tgz
# Use: node package/dist/cli.cjs

# Or build from source
pnpm install && pnpm build
# Use: node dist/cli.cjs

2. Fetch dependencies (online)

node cli.cjs fetch -l ./pnpm-lock.yaml -o ./packages

3. Transfer to airgap

Copy the packages folder and cli.cjs to your air-gapped environment.

4. Publish to local registry (airgap)

# Start your registry (e.g., Verdaccio)
verdaccio &

# Login
npm login --registry http://localhost:4873

# Publish all packages
node cli.cjs publish -p ./packages -r http://localhost:4873

5. Install your project

pnpm install --registry http://localhost:4873

Interactive Mode

Run without arguments for a guided wizard:

node cli.cjs

┌───────────────────────────────────────┐
│  pnpm-airgap v2.4.0                   │
│  Transfer dependencies to air-gapped  │
│  environments with ease               │
└───────────────────────────────────────┘

? What would you like to do?
  ❯ 📦 Fetch dependencies from lockfile
    📤 Publish packages to registry
    🔄 Sync registries
    📊 Export registry state
    📖 Quick start guide
    ✖ Exit

Commands

`fetch` - Download packages from lockfile

node cli.cjs fetch [options]

Options:
  -l, --lockfile <path>      Path to pnpm-lock.yaml (default: ./pnpm-lock.yaml)
  -o, --output <path>        Output directory (default: ./airgap-packages)
  -r, --registry <url>       Source registry (default: https://registry.npmjs.org)
  --registry-state <path>    Registry state file for incremental fetching
  --skip-optional            Skip optional dependencies
  --concurrency <number>     Parallel downloads (default: 5)
  --debug                    Enable debug output

`publish` - Publish packages to registry

node cli.cjs publish [options]

Options:
  -p, --packages <path>      Packages directory (default: ./airgap-packages)
  -r, --registry <url>       Target registry (default: http://localhost:4873)
  --concurrency <number>     Parallel publishes (default: 3)
  --no-skip-existing         Publish all packages even if they exist
  --dry-run                  Preview without publishing
  --debug                    Enable debug output

Publish reliability (v2.4.0)

Publishing to a private registry has subtle failure modes — publish is hardened against them:

Authenticated skip-existing. The existence pre-check now authenticates exactly like npm publish does, covering every scheme npm supports — _authToken (bearer), _auth, and username + _password (basic, which is what a default Verdaccio htpasswd setup writes) — plus NPM_TOKEN / NODE_AUTH_TOKEN. Credentials are read from the raw .npmrc files in npm precedence order (project .npmrc, then --userconfig, globalconfig, ~/.npmrc), because npm 9+ protects auth keys: npm config get "//host/:_authToken" errors instead of returning the value. Previously, on an auth-gated registry the probe got 401, every package looked "uncertain", and re-runs silently re-published everything. Now an already-populated registry is correctly skipped — re-publish is a true no-op, not a reflush.
Per-package-name serialization. Versions of the same package are published sequentially (different packages still run in parallel up to --concurrency). Verdaccio's manifest update is a non-atomic read-modify-write; publishing two versions of one package concurrently can race so that a tarball lands but its manifest entry is lost — an orphan (409 on re-publish, 404 on fetch). Serializing per name removes that race at the source.
Orphan detection, not silent skip. A 409 Conflict is verified against the manifest: if the version is really there, it's an idempotent skip; if the tarball exists but the version is absent from the manifest, it's reported as an ORPHAN error (non-zero exit) with the exact storage path — never masked as success. Orphans can only be cleared by deleting the stray .tgz from the registry host's storage and re-publishing (no HTTP API can remove a manifest-absent tarball), so run a periodic orphan sweep on the registry host if multiple machines publish concurrently.

`sync` - Sync between registries

node cli.cjs sync [options]

Options:
  -s, --source <url>         Source registry URL
  -d, --dest <url>           Destination registry URL
  -o, --output <path>        Output directory
  --scope <scope>            Only sync packages in this scope
  --download-only            Only download, don't publish
  --publish-only             Only publish existing packages
  --dry-run                  Preview without changes

`registry-state export` - Export for incremental sync

Export all packages from a registry to enable incremental fetching:

node cli.cjs registry-state export -r http://localhost:4873 -o registry-state.json

# Then use with fetch to skip existing packages
node cli.cjs fetch -l pnpm-lock.yaml --registry-state registry-state.json

`prune` - Remove stale versions from a registry

Private registries (Verdaccio, etc.) have no garbage collection - every published version stays forever, so a long-lived airgap registry bloats with old versions no project installs anymore. prune trims a registry down to the union of your consumer lockfiles: any version not referenced by a lockfile is safe to remove.

# Dry-run (default): show what would be removed, delete nothing
node cli.cjs prune -l ./pnpm-lock.yaml -r http://localhost:4873

# Multiple consumers: keep-set is the UNION of all their lockfiles
node cli.cjs prune -l repoA/pnpm-lock.yaml -l repoB/pnpm-lock.yaml -r http://localhost:4873

# Execute the removals
node cli.cjs prune -l ./pnpm-lock.yaml -r http://localhost:4873 --yes

Options:
  -l, --lockfile <paths...>  One or more pnpm-lock.yaml paths (union = keep-set)
  -r, --registry <url>       Registry URL
  --prune-orphans            Also remove whole packages absent from every lockfile
  --keep <names...>          Package names protected from orphan removal
  --concurrency <number>     Parallel unpublishes (default: 5)
  --yes                      Execute removals (default is dry-run)
  --debug                    List every version in the plan

Safety: prune works at version granularity, never package granularity - it only removes stale versions of packages your lockfile references. Packages absent from every lockfile (e.g. tooling you published deliberately) are left completely untouched unless you opt in with --prune-orphans. Removals use npm unpublish, so the registry trims its own manifest + tarball; no on-disk surgery. Anything pruned reappears the next time you publish a lockfile that needs it.

Why not "keep newest N versions"? Because a transitive dependency can pin an exact old version - "keep newest N" would delete it and break offline --frozen-lockfile installs. The lockfile union always keeps exactly what every install needs, no more, no less.

Tip: run prune as the second half of a sync - publish the new closure first (adds current versions), then prune to the same lockfile (removes what dropped out). Never prune below the lockfile your target environment actually runs.

`info` - Show bundle information

node cli.cjs info ./packages

`init` - Create config file

node cli.cjs init

Configuration

Create pnpm-airgap.config.json:

{
  "fetch": {
    "lockfilePath": "./pnpm-lock.yaml",
    "outputDir": "./airgap-packages",
    "concurrency": 5,
    "registryUrl": "https://registry.npmjs.org",
    "skipOptional": false
  },
  "publish": {
    "packagesDir": "./airgap-packages",
    "registryUrl": "http://localhost:4873",
    "concurrency": 3,
    "skipExisting": true
  },
  "sync": {
    "sourceRegistry": "",
    "destRegistry": "http://localhost:4873",
    "outputDir": "./sync-packages",
    "skipExisting": true
  }
}

Features

Feature	Description
Standalone Binary	Single 1.1MB file, runs with just Node.js - no npm install needed
Interactive Mode	Guided wizard for all commands
Auto-detection	Finds lockfiles and package directories automatically
Incremental Sync	Export registry state to skip already-synced packages
Storage Prune	Trim a registry to the union of consumer lockfiles (reclaims GBs)
Smart Tagging	Auto-detects prerelease tags, handles version conflicts
Safety Blocks	Prevents accidental publish to public registries (npmjs.org)
Rate Limiting	Automatic backoff for 429 errors
Robust Parsing	Handles scoped packages, aliases, patches, peer deps

Workflow Examples

Complete Airgap Transfer

Online Machine:

# Fetch all dependencies
node cli.cjs fetch -l pnpm-lock.yaml -o ./packages

# Create transfer archive
tar -czf transfer.tar.gz packages/ cli.cjs

Offline Machine:

# Extract
tar -xzf transfer.tar.gz

# Start registry and login
verdaccio &
npm login --registry http://localhost:4873

# Publish
node cli.cjs publish -p ./packages -r http://localhost:4873

# Install your project
echo "registry=http://localhost:4873" > .npmrc
pnpm install

Incremental Updates

Avoid re-downloading packages that already exist:

# Export state from airgap registry
node cli.cjs registry-state export -r http://verdaccio:4873 -o state.json

# Transfer state.json to online machine

# Fetch only missing packages
node cli.cjs fetch -l pnpm-lock.yaml --registry-state state.json -o ./packages
# Result: If lockfile needs 500 packages but 450 exist, only 50 are downloaded

Keeping the Registry Lean

A no-uplink registry grows forever. Reclaim space by pruning to what you actually install:

# Preview (safe) - see how much is stale
node cli.cjs prune -l pnpm-lock.yaml -r http://verdaccio:4873

# Reclaim - publish current closure, then prune to the same lockfile
node cli.cjs publish -p ./packages -r http://verdaccio:4873
node cli.cjs prune   -l pnpm-lock.yaml -r http://verdaccio:4873 --yes
# Result: registry == exactly your lockfile closure; stale versions gone

Programmatic API

import { fetchDependencies, publishPackages } from 'pnpm-airgap';

// Fetch
await fetchDependencies({
  lockfilePath: './pnpm-lock.yaml',
  outputDir: './packages',
  registryUrl: 'https://registry.npmjs.org',
  concurrency: 5,
});

// Publish
await publishPackages({
  packagesDir: './packages',
  registryUrl: 'http://localhost:4873',
  concurrency: 3,
  skipExisting: true,
});

Compatibility

Component	Supported Versions
Node.js	18.0.0 or higher
pnpm lockfile	v5, v6, v9
Registries	Verdaccio, Nexus, Artifactory, any npm-compatible
Platforms	Windows, Linux, macOS

Reports

Both fetch and publish commands generate JSON reports:

metadata.json - Package list and metadata
bundle-info.json - Download statistics
publish-report.json - Publishing results

Troubleshooting

Authentication Issues

# Verify you're logged in
npm whoami --registry http://localhost:4873

# Re-login if needed
npm login --registry http://localhost:4873

"Pre-check: 0 exist" on a registry you know is populated. The pre-check could not authenticate, so every probe returned 401 and was recorded as "uncertain" (which counts as "to publish"). The run still succeeds — each existing package is skipped on a 409 — but it re-uploads the whole closure to find that out. Confirm the credentials the pre-check sees:

# Should print 200, not 401
curl -s -o /dev/null -w "%{http_code}\n" --user "<user>:<pass>" http://localhost:4873/lodash

Then check .npmrc has an entry for that exact host (//host:port/:_authToken=…, or username + _password). Note the host key must match the registry URL including port. Run with --debug to see which file the credentials were resolved from.

Missing Packages

Check bundle-info.json for download failures and ensure lockfile is current.

Publishing Conflicts

The tool automatically handles:

Version conflicts (uses version-specific tags)
Prerelease versions (applies correct tags)
Already-existing packages (skips by default)

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

# Lint
pnpm lint

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Name		Name	Last commit message	Last commit date
src		src
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc		.prettierrc
README.md		README.md
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

pnpm-airgap

The Problem

The Solution

Quick Start

1. Download the standalone CLI

2. Fetch dependencies (online)

3. Transfer to airgap

4. Publish to local registry (airgap)

5. Install your project

Interactive Mode

Commands

fetch - Download packages from lockfile

publish - Publish packages to registry

Publish reliability (v2.4.0)

sync - Sync between registries

registry-state export - Export for incremental sync

prune - Remove stale versions from a registry

info - Show bundle information

init - Create config file