plunk

Local npm package development without symlinks. Copies built files directly into consumer node_modules/ with incremental sync, watch mode, and support for every package manager and bundler.

npx plunk init       # set up your app
plunk add my-lib     # link a package
plunk dev            # watch → build → push (continuous)

Why plunk?

npm link creates symlinks that break module resolution — duplicate React instances, peer dep mismatches, bundlers that can't follow links outside the project root. Tools like yalc improved on this by copying files instead, but still modify package.json and lack built-in watch mode.

plunk copies built files directly into node_modules/ without touching your package.json or lock file. Incremental sync (xxhash diffing + mtime fast-skip), built-in watch mode, and multi-consumer push make it practical for daily development across projects.

How it works

graph LR
    A["my-lib/"] -- "plunk publish" --> B["~/.plunk/store/<br/>[email protected]"]
    B -- "plunk add" --> C["app/node_modules/<br/>my-lib/"]
    B -- "plunk push" --> D["app-2/node_modules/<br/>my-lib/"]

    style A fill:#2e7d32,stroke:#66bb6a,color:#e8f5e9
    style B fill:#1565c0,stroke:#64b5f6,color:#e3f2fd
    style C fill:#e65100,stroke:#ffb74d,color:#fff3e0
    style D fill:#e65100,stroke:#ffb74d,color:#fff3e0

1. publish copies built files to a local store at ~/.plunk/store/
2. add copies from store into your app's node_modules/
3. push = publish + copy to all consumers
4. dev = watch → build → push loop (or push --watch)

Uses CoW reflinks for instant copy-on-write on APFS/btrfs/ReFS, with automatic fallback. Reflink support is probed once per volume and cached — no wasted syscalls. Only changed files are re-copied (xxhash-based diffing).

Quick start

# In your app — one-time setup
cd my-app
npx plunk init

# In your library — build and publish to plunk store
cd my-lib
pnpm build
plunk publish

# Back in your app — link the library
cd my-app
plunk add my-lib

# Continuous dev: watch → build → push (auto-detects build command)
cd my-lib
plunk dev

At a glance

| | npm link | yalc | plunk | | ---------------------- | ----------------------- | --------------------------- | ------------------- | | Mechanism | Symlinks | Copy + package.json rewrite | Copy only | | Module resolution | Broken (dual instances) | Works | Works | | Git contamination | None | package.json + .yalc/ | None | | Bundler HMR | Often broken | Varies | Works | | pnpm support | Fragile | Limited | Full | | Watch mode | None | External | Built-in | | Survives npm install | No | No | plunk restore | | Incremental sync | N/A | Full copy each time | mtime + xxhash diff |

See detailed comparison for a deeper breakdown.

Install

pnpm add -g @olegkuibar/plunk       # or npm, yarn, bun
npx @olegkuibar/plunk init          # set up a consumer project

Try it online

Open Playground — run plunk publish, plunk add, and plunk push in the browser with live HMR preview.

Documentation

| | | | -------------------------------------------------- | -------------------------------------------- | | Getting Started | Install, first publish/add cycle, watch mode | | Commands | Every command, every flag | | How It Works | Store format, injection, CoW copies | | Bundler Guide | Vite, Webpack, esbuild, Turbopack setup | | Comparison | npm link vs yalc vs plunk | | CI/CD | Using plunk in CI pipelines | | Monorepo Guide | Workspace setup and recursive publish | | Troubleshooting | Common issues and fixes | | FAQ | Frequently asked questions | | Migrating from yalc | Step-by-step migration guide | | Architecture | Internals for contributors | | API Reference | Programmatic API (TypeScript) | | Examples | Try it yourself with real packages | | Playground | Interactive browser-based playground | | Contributing | Dev setup and guidelines |

Acknowledgments

plunk and its playground are built on top of excellent open-source projects:

• chokidar — file watching
• xxhash-wasm — fast file hashing for incremental sync
• citty — CLI framework
• tsup — TypeScript bundler
• vitest — test runner
• WebContainers — in-browser Node.js runtime (playground)
• Vite — frontend tooling
• React — UI framework
• Monaco Editor — code editor (playground)
• xterm.js — terminal emulator (playground)
• Tailwind CSS — styling

Thank you to the maintainers and contributors of these projects.

License

MIT