samhail

library0.2.0jsnpmunverified

Samhail is a developer tool designed to streamline local npm package development by resolving linked packages directly at the bundler level. It provides an alternative to traditional methods like `npm link`, avoiding issues related to symlinks, `node_modules` mutation, or lockfile changes. The system operates in two parts: a CLI for managing configuration (`.samhail.json`) and session state (`.samhail.lock`), and bundler-specific plugins (for Vite, Webpack, Rspack, esbuild, Rollup) that rewrite module resolution when a session is active. This ensures that a consumer application directly uses the local source of a dependency without interfering with the global `node_modules` structure. Currently at version 0.2.0, it is in an early development stage, implying rapid iteration and potential for breaking changes, though no specific release cadence is published beyond active development. Its core differentiator is the bundler-level resolution and the avoidance of common `npm link` pitfalls.

devops

npm install samhail

github ↗package ↗

INSTALL

IMPORT

SIG · SAMHAIL

samhail

devopsjavascriptv0.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

samhail

✓ import samhail from 'samhail/vite';

Imports are specific to the bundler being used. This example is for Vite. Other bundlers use subpaths like `samhail/webpack` or `samhail/rollup`.

samhail

✓ import samhail from 'samhail/webpack';

For Webpack projects, import the plugin from the 'samhail/webpack' subpath. Ensure your bundler is correctly configured to use this plugin.

samhail

✓ import samhail from 'samhail/esbuild';

When using esbuild as your bundler, import the plugin from 'samhail/esbuild'. Each bundler integration is provided via its own entry point.

Demonstrates how to integrate Samhail into a Vite project, link a local package, and activate a development session for bundler-level resolution.

import { defineConfig } from 'vite'; import samhail from 'samhail/vite'; // vite.config.ts export default defineConfig({ plugins: [samhail()], }); // In your terminal: // npm install samhail --save-dev // npx samhail link // (Follow prompts to link a local package, e.g., './my-local-package') // npx samhail start // (Run your Vite dev server in another terminal: npm run dev)

samhail --version

Debug

Known issues

gotchaSamhail's bundler plugin is a no-op unless `npx samhail start` is actively running. If you forget to start the session, your bundler will resolve dependencies from `node_modules` normally, potentially leading to confusion if local changes aren't reflected.

fix

Always run `npx samhail start` in a dedicated terminal before starting your bundler's dev server. Verify the `.samhail.lock` file exists while developing.

affects: >=0.2.0

gotchaThe configuration file `.samhail.json` and the session lock file `.samhail.lock` are project-specific and should not be committed to version control. Failing to add them to `.gitignore` can lead to conflicts or incorrect behavior in other environments.

fix

Add both `.samhail.json` and `.samhail.lock` to your project's `.gitignore` file immediately after installation.

affects: >=0.2.0

breakingAs of version 0.2.0, Samhail is in an early development stage. Future minor or patch releases may introduce breaking API changes as the project matures and stabilizes. Always review release notes when upgrading.

fix

Pin to specific patch versions (e.g., `~0.2.0` instead of `^0.2.0`) in your `package.json` for stability, and thoroughly test upgrades when new versions are released.

affects: <1.0.0

Errors

Common errors & fixes

Error: Module not found: Error: Can't resolve 'your-linked-package' in '/path/to/your/consumer/app'

The Samhail session (`npx samhail start`) is not running, or the package is not correctly linked in `.samhail.json`.

fix

Ensure `npx samhail start` is running in a separate terminal. Verify your `package.json` correctly lists 'your-linked-package' as a dependency and `npx samhail link` successfully configured it in `.samhail.json`.

Error: [vite] The 'samhail' plugin was configured but no active Samhail session was found. Make sure 'npx samhail start' is running.

The bundler plugin detected an inactive Samhail session, reverting to default module resolution.

fix

Execute `npx samhail start` in your project's root directory. This will create a `.samhail.lock` file, indicating an active session.

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/joshhbk/samhail ↗

packagehttps://www.npmjs.com/package/samhail ↗