samhail

Develop local npm packages against a consumer app without symlinks, lockfile changes, or node_modules mutation. Resolves linked packages at the bundler level.

Install

npm install samhail --save-dev

Quick start

1. Add the plugin to your bundler

// vite.config.ts
import samhail from "samhail/vite";

export default defineConfig({
  plugins: [samhail()],
});

Also available for Webpack, Rspack, esbuild, and Rollup:

import samhail from "samhail/webpack";
import samhail from "samhail/rspack";
import samhail from "samhail/esbuild";
import samhail from "samhail/rollup";

2. Link a local package

npx samhail link

This walks you through picking a dependency and pointing it at a local directory. The result is a .samhail.json file in your project root.

3. Start a session

npx samhail start

This activates the session and maintains a heartbeat file (.samhail.lock). While running, the bundler plugin resolves linked packages from their local directories instead of node_modules.

Run your package build commands separately (in other terminals, via your task runner, etc).

Press Ctrl+C to stop.

CLI commands

Command	Description
samhail link	Link a dependency to a local directory
samhail unlink	Remove a linked package
samhail relink	Restore previously linked packages from history
samhail start	Start a session for linked packages
samhail status	Show linked packages and session state
samhail tsconfig	Print tsconfig paths for linked packages

How it works

The system has two halves that communicate through a small filesystem contract:

• CLI manages config (.samhail.json) and session state (.samhail.lock)
• Bundler plugin reads the config, checks if a session is active, and rewrites module resolution for linked packages

When samhail start is running, the plugin resolves imports of linked packages to their local directories. When it's not running, the plugin is a no-op and your bundler behaves normally.

Config

samhail link generates a .samhail.json file:

{
  "links": {
    "@myorg/shared": {
      "path": "../shared"
    }
  }
}

Add .samhail.json and .samhail.lock to your .gitignore.

License

MIT