Documentation

PacketNinja wraps your package manager commands in a controlled, local environment. No workflow changes required.

Installation

No installation required. Use npx to run PacketNinja directly:

terminal

npx package-ninja dev

First Run

PacketNinja automatically detects your package manager and starts a local registry:

terminal

$ npx package-ninja dev
[session] Starting local registry on 127.0.0.1:4873
[session] Detected package manager: npm
✓ Installed 42 packages in 1.2s
✓ Running dev script
Ready http://localhost:3000

Commands

npx package-ninja devStart dev server with controlled session

npx package-ninja installInstall dependencies through local registry

npx package-ninja testRun tests in isolated environment

npx package-ninja publishPublish with safety checks

npx package-ninja startCreate persistent session

npx package-ninja stopStop and clean up session

CLI Flags

--cwd <path>Target project directory

--pm <npm|pnpm|yarn>Override package manager detection

--port <number>Preferred local registry port

--persistentKeep a reusable local session

--offlineDisable npmjs uplink

--installForce install before dev

Session Control

Ephemeral sessions clean up automatically. Persistent sessions stay alive for repeated commands:

terminal

# Persistent session
npx package-ninja start
npx package-ninja run -- npm install
npx package-ninja run -- npm test
npx package-ninja stop

Publish Safety

PacketNinja blocks publishes when publishConfig.registry points to a non-local registry:

⚠

Publish Blocked

Target registry is not local. Use --force to override.

Need help? Open an issue on GitHub