{"id":13975,"library":"samhail","title":"Samhail: Local Package Development","description":"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.","status":"active","version":"0.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/joshhbk/samhail","tags":["javascript","local-development","npm-link","bundler-plugin","vite","webpack","rspack","esbuild","rollup"],"install":[{"cmd":"npm install samhail","lang":"bash","label":"npm"},{"cmd":"yarn add samhail","lang":"bash","label":"yarn"},{"cmd":"pnpm add samhail","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Imports are specific to the bundler being used. This example is for Vite. Other bundlers use subpaths like `samhail/webpack` or `samhail/rollup`.","symbol":"samhail","correct":"import samhail from 'samhail/vite';"},{"note":"For Webpack projects, import the plugin from the 'samhail/webpack' subpath. Ensure your bundler is correctly configured to use this plugin.","symbol":"samhail","correct":"import samhail from 'samhail/webpack';"},{"note":"When using esbuild as your bundler, import the plugin from 'samhail/esbuild'. Each bundler integration is provided via its own entry point.","symbol":"samhail","correct":"import samhail from 'samhail/esbuild';"}],"quickstart":{"code":"import { defineConfig } from 'vite';\nimport samhail from 'samhail/vite';\n\n// vite.config.ts\nexport default defineConfig({\n  plugins: [samhail()],\n});\n\n// In your terminal:\n// npm install samhail --save-dev\n// npx samhail link\n// (Follow prompts to link a local package, e.g., './my-local-package')\n// npx samhail start\n// (Run your Vite dev server in another terminal: npm run dev)","lang":"typescript","description":"Demonstrates how to integrate Samhail into a Vite project, link a local package, and activate a development session for bundler-level resolution."},"warnings":[{"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.","message":"Samhail'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.","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Add both `.samhail.json` and `.samhail.lock` to your project's `.gitignore` file immediately after installation.","message":"The 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.","severity":"gotcha","affected_versions":">=0.2.0"},{"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.","message":"As 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.","severity":"breaking","affected_versions":"<1.0.0"}],"env_vars":null,"search_vec":"'0.2.0':108 'activ':82,132 'altern':29 'applic':88 'avoid':36,145 'beyond':131 'break':122 'bundler':24,65,140,159 'bundler-level':139 'bundler-plugin':158 'bundler-specif':64 'cadenc':128 'chang':46,123 'cli':54 'common':147 'configur':57 'consum':87 'core':135 'current':105 'depend':96 'design':10 'develop':4,8,16,114,133,154 'differenti':136 'direct':21,89 'earli':113 'ensur':84 'esbuild':72,164 'global':101 'impli':116 'interf':98 'issu':37 'iter':118 'javascript':151 'level':25,141 'like':33 'link':19,35,149,157 'local':2,13,92,153 'local-develop':152 'lockfil':45 'manag':56 'method':32 'modul':42,76,103 'mutat':43 'node':41,102 'npm':14,34,148,156 'npm-link':155 'oper':49 'packag':3,15,20 'part':52 'pitfal':150 'plugin':67,160 'potenti':120 'provid':27 'publish':130 'rapid':117 'relat':38 'releas':127 'resolut':77,142 'resolv':18 'rewrit':75 'rollup':73,165 'rspack':71,163 'samhail':1,5 'samhail.json':58 'samhail.lock':62 'session':60,80 'sourc':93 'specif':66,126 'stage':115 'state':61 'streamlin':12 'structur':104 'symlink':40 'system':48 'though':124 'tool':9 'tradit':31 'two':51 'use':90 'version':107 'vite':69,161 'webpack':70,162 'without':97","created_at":"2026-04-20T01:57:16.878178+00:00","updated_at":"2026-04-20T01:57:16.878178+00:00","problems":[{"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`.","cause":"The Samhail session (`npx samhail start`) is not running, or the package is not correctly linked in `.samhail.json`.","error":"Error: Module not found: Error: Can't resolve 'your-linked-package' in '/path/to/your/consumer/app'"},{"fix":"Execute `npx samhail start` in your project's root directory. This will create a `.samhail.lock` file, indicating an active session.","cause":"The bundler plugin detected an inactive Samhail session, reverting to default module resolution.","error":"Error: [vite] The 'samhail' plugin was configured but no active Samhail session was found. Make sure 'npx samhail start' is running."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"samhail","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/joshhbk/samhail","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/samhail","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}