Knarr

Test local npm packages in real apps without npm link, duplicate React, or dirty package.json diffs.

Knarr copies the built package output directly into the consumer app's node_modules/, so your package behaves like the version you would publish to npm. It works well with pnpm, Vite, Next.js, Webpack/rspack, Turbopack, and teams that want local package overrides to stay out of git.

cd my-app
npx knarr use ../my-lib

cd ../my-lib
knarr dev

If you have not installed Knarr globally, use npx knarr dev for the second command too.

Who this is for

• Library and design-system authors testing packages inside real consumer apps
• React developers avoiding duplicate React instances and invalid hook calls from symlinks
• pnpm users where npm link or yalc do not match the installed dependency tree
• Teams that want clean git diffs while iterating on local packages

Why Knarr?

npm link creates symlinks that can break module resolution: duplicate React instances, peer dependency mismatches, and bundlers that cannot follow links outside the project root. yalc improves this by copying files, but it rewrites consumer dependency specs and usually needs extra watch tooling.

Knarr keeps your package.json and lockfile clean. It publishes a local package into ~/.knarr/store/, injects that package into every registered consumer, and can watch, rebuild, and push changes continuously.

Quick Start

One command links a local package into the app you are testing:

# In your app
cd my-app
npx knarr use ../my-lib

Then run the continuous package dev loop from the library:

# In your library
cd ../my-lib
knarr dev

If Knarr is not installed globally, run npx knarr dev instead.

That is the everyday loop: edit my-lib, Knarr rebuilds it, pushes changed files into my-app/node_modules/, and your bundler sees the update.

If you prefer the explicit steps:

cd my-lib
pnpm build
knarr publish

cd ../my-app
knarr add my-lib

How It Works

graph LR
    A["my-lib/"] -- "knarr publish" --> B["~/.knarr/store/<br/>[email protected]"]
    B -- "knarr use ../my-lib<br/>or knarr add my-lib" --> C["app/node_modules/<br/>my-lib/"]
    B -- "knarr 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 ~/.knarr/store/
2. use publishes from a local path and links it into the current app
3. add links an already-published package from the store
4. push publishes and copies to all registered consumers
5. dev watches, builds, publishes, and pushes continuously

At A Glance

| | npm link | yalc | Knarr | | ---------------------- | ----------------------- | --------------------------- | ------------------- | | 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 | knarr restore | | Incremental sync | N/A | Full copy each time | mtime + xxhash diff |

See detailed comparison for a deeper breakdown.

Migrate From yalc In 60 Seconds

cd my-app
npx knarr migrate
npx knarr use ../my-lib

cd ../my-lib
knarr dev

See Migrating from yalc for the full guide.

Install

pnpm add -g knarr       # or npm, yarn, bun
npx knarr init          # one-off setup for a consumer project

Performance Notes

knarr uses CoW reflinks for instant copy-on-write on APFS/btrfs/ReFS, with automatic fallback. Reflink support is probed once per volume and cached. Incremental sync checks size and mtime first, then falls back to xxhash only when needed, so unchanged files are skipped quickly.

Documentation

• Getting Started
• Commands
• Comparison
• Troubleshooting
• Examples
• Contributing

Additional guides for bundlers, CI, monorepos, internals, and the experimental programmatic API live in docs/.

Acknowledgments

Knarr is built on top of excellent open-source projects:

• chokidar - file watching
• xxhash-wasm - fast file hashing
• citty - CLI framework
• tsup - TypeScript bundler
• vitest - test runner
• Vite - frontend tooling

License

MIT