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.0.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

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

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
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

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

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.