{"id":28491264,"url":"https://github.com/statico/lockfile-guardian","last_synced_at":"2026-03-15T00:50:09.348Z","repository":{"id":297358921,"uuid":"995168652","full_name":"statico/lockfile-guardian","owner":"statico","description":"⚙️ Node.js tool that detects when your npm/yarn/pnpm lockfiles change after git operations","archived":false,"fork":false,"pushed_at":"2025-06-06T19:07:59.000Z","size":76,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-09T10:11:36.780Z","etag":null,"topics":["lockfiles","monorepo","node","node-js","node-modules","nodejs","npm","npmjs","pnpm","typescript","yarn"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/lockfile-guardian","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/statico.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-03T04:29:18.000Z","updated_at":"2025-06-06T18:57:09.000Z","dependencies_parsed_at":null,"dependency_job_id":"14538cc8-cdca-429c-b89d-32881cd8dfec","html_url":"https://github.com/statico/lockfile-guardian","commit_stats":null,"previous_names":["statico/lockfile-guardian"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/statico/lockfile-guardian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Flockfile-guardian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Flockfile-guardian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Flockfile-guardian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Flockfile-guardian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/statico","download_url":"https://codeload.github.com/statico/lockfile-guardian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Flockfile-guardian/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269739917,"owners_count":24467746,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lockfiles","monorepo","node","node-js","node-modules","nodejs","npm","npmjs","pnpm","typescript","yarn"],"created_at":"2025-06-08T08:06:41.383Z","updated_at":"2026-03-15T00:50:09.269Z","avatar_url":"https://github.com/statico.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔒 Lockfile Guardian\n\n[![GitHub repo](https://img.shields.io/badge/github-repo-green)](https://github.com/statico/lockfile-guardian) [![npm](https://img.shields.io/npm/v/lockfile-guardian.svg)](https://www.npmjs.com/package/lockfile-guardian) [![Test](https://github.com/statico/lockfile-guardian/workflows/Test/badge.svg)](https://github.com/statico/lockfile-guardian/actions?query=workflow%3ATest) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/statico/lockfile-guardian/blob/main/LICENSE)\n\nNever forget to install dependencies again! Automatically detect when your lock files change after git operations and warn you (or auto-install) when your dependencies are out of sync.\n\n## The Problem\n\nYou know this scenario:\n\n- Teammate adds a new dependency\n- You `git pull` or switch branches\n- Your code breaks because you forgot to run `npm install`\n- You spend 10 minutes debugging before realizing the issue\n\n## The Solution\n\nLockfile Guardian installs git hooks that automatically detect when your lock files have changed and either warn you or auto-install dependencies.\n\n## Features\n\n- 🎯 **Zero runtime dependencies** - Pure Node.js implementation\n- 🔍 **Smart detection** - Auto-detects npm, yarn, or pnpm lock files\n- ⚡ **One-command setup** - `npx lockfile-guardian install` and you're done\n- 🪝 **Git hooks** - Works on checkout, pull, merge, and branch switching\n- 🔧 **Configurable** - Optional auto-install and silent modes\n- 📦 **TypeScript** - Built with TypeScript, works with any Node.js project\n- 🧹 **Clean** - Stores metadata in `.git/` directory, not your working tree\n- ⚠️ **Visual warnings** - Eye-catching alerts when dependencies are out of sync\n- 🐶 **Husky compatible** - Works seamlessly with Husky, lint-staged, prettier, and other tools\n\n## Quick Start\n\n```bash\n# Install and setup git hooks (one time only)\nnpx lockfile-guardian install\n\n# That's it! Now every git operation checks your dependencies\n```\n\n## How It Works\n\n1. **Secure tracking** - Stores SHA256 hash of your lock file in `.git/lockfile-guardian`\n2. **Git integration** - Installs hooks for post-checkout, post-merge, and post-rewrite\n3. **Smart detection** - Automatically finds and monitors the right lock file\n4. **Helpful warnings** - Shows exactly which command to run for your package manager\n5. **Optional automation** - Can automatically install dependencies if configured\n\n## Husky Compatibility\n\nLockfile Guardian is **fully compatible** with [Husky](https://typicode.github.io/husky/) and works seamlessly alongside other tools:\n\n### ✅ What Works\n\n- **Husky v4+** - Automatically detects and uses `.husky/` directory\n- **lint-staged** - Runs after linting and formatting tools\n- **prettier** - Compatible with prettier hooks\n- **ESLint** - Works with ESLint pre-commit hooks\n- **Traditional hooks** - Falls back to `.git/hooks/` when Husky isn't detected\n\n### 🔧 How It Works\n\n```bash\n# Your existing .husky/pre-commit\n#!/usr/bin/env sh\n. \"$(dirname -- \"$0\")/_/husky.sh\"\n\nnpx lint-staged\n\n# After installing lockfile-guardian, your .husky/post-checkout becomes:\n#!/usr/bin/env sh\n. \"$(dirname -- \"$0\")/_/husky.sh\"\n\n# Your existing hooks run first...\n\n# Lockfile Guardian\nnpx lockfile-guardian check --hook\n```\n\n### 🚀 Setup with Husky\n\nIf you're already using Husky, just install normally:\n\n```bash\nnpx lockfile-guardian install\n```\n\nLockfile Guardian will:\n\n- ✅ Detect your Husky setup automatically\n- ✅ Install hooks in `.husky/` directory\n- ✅ Preserve all existing hook configurations\n- ✅ Run **after** your other tools (lint-staged, prettier, etc.)\n\n### 📋 Example Integration\n\n```json\n{\n  \"scripts\": {\n    \"prepare\": \"husky\"\n  },\n  \"lint-staged\": {\n    \"*.{js,ts,tsx}\": [\"prettier --write\", \"eslint --fix\"],\n    \"*.{json,md}\": [\"prettier --write\"]\n  },\n  \"lockfileGuardian\": {\n    \"autoInstall\": true,\n    \"silent\": false\n  }\n}\n```\n\n## Configuration\n\nAdd optional configuration to your `package.json`:\n\n```json\n{\n  \"lockfileGuardian\": {\n    \"autoInstall\": true, // Automatically run install commands\n    \"silent\": false, // Suppress non-warning output\n    \"checkNodeModules\": true // Warn if node_modules isn't gitignored (default: true)\n  }\n}\n```\n\n## Commands\n\n```bash\n# Setup git hooks (one-time setup)\nnpx lockfile-guardian install\n\n# Remove all hooks and cleanup\nnpx lockfile-guardian uninstall\n\n# Manually check for lock file changes\nnpx lockfile-guardian check\n\n# Show help and current configuration\nnpx lockfile-guardian\n```\n\n## Supported Package Managers\n\nAutomatically detects and supports:\n\n- **pnpm** - `pnpm-lock.yaml` → `pnpm install`\n- **Yarn** - `yarn.lock` → `yarn install`\n- **npm** - `package-lock.json` → `npm install`\n\nDetection priority: pnpm → yarn → npm (first lock file found wins)\n\n## Example Output\n\n### Basic Warning\n\n```bash\n$ git checkout feature/new-deps\n=====================================\n⚠️  DEPENDENCIES OUT OF DATE  ⚠️\n=====================================\nLock file pnpm-lock.yaml has changed!\n\nRun this command to update:\n  pnpm install\n=====================================\n```\n\n### With Auto-Install\n\n```bash\n$ git pull origin main\n🔒 Lock file yarn.lock has changed!\n🔒 Auto-installing dependencies with yarn...\nyarn install v1.22.19\n[1/4] 🔍  Resolving packages...\n[2/4] 🚚  Fetching packages...\n[3/4] 🔗  Linking dependencies...\n[4/4] 🔨  Building fresh packages...\n✨ Done in 2.34s.\n🔒 Dependencies updated successfully!\n```\n\n## What Gets Created\n\n**Git hooks:**\n\n- `.git/hooks/post-checkout` - Runs after branch switching\n- `.git/hooks/post-merge` - Runs after `git pull`/`git merge`\n- `.git/hooks/post-rewrite` - Runs after `git rebase`\n\n**Metadata:**\n\n- `.git/lockfile-guardian` - Stores hash of current lock file\n\n**Nothing in your working directory!** All tool data stays in `.git/` where it belongs.\n\n## Safety Features\n\n- **Non-destructive** - Only reads lock files, never modifies them\n- **Git validation** - Ensures you're in a git repository before installing\n- **Gitignore check** - Warns if `node_modules` isn't properly ignored\n- **Safe uninstall** - Completely removes all traces when uninstalled\n- **Error handling** - Graceful failure if install commands fail\n\n## Why Use This?\n\n**For individuals:**\n\n- Never waste time debugging dependency issues again\n- Automatic detection works seamlessly in the background\n- Zero maintenance after initial setup\n\n**For teams:**\n\n- Ensures everyone has the same dependencies installed\n- Prevents \"works on my machine\" issues\n- Catches dependency updates immediately after pulling changes\n- Reduces onboarding friction for new team members\n\n## Comparison with Alternatives\n\n| Tool                  | Setup               | Auto-install       | Zero deps | Git integrated  | Husky compatible |\n| --------------------- | ------------------- | ------------------ | --------- | --------------- | ---------------- |\n| **Lockfile Guardian** | ✅ One command      | ✅ Optional        | ✅ Yes    | ✅ Native hooks | ✅ Yes           |\n| `@antfu/ni`           | ❌ Manual usage     | ❌ Manual          | ❌ No     | ❌ No           | ❌ No            |\n| Manual git hooks      | ❌ Complex setup    | ❌ Script required | ✅ Yes    | ✅ Yes          | ⚠️ Manual        |\n| IDE extensions        | ❌ Per-editor setup | ❌ Usually not     | ❌ No     | ❌ No           | ❌ No            |\n\n## Requirements\n\n- Node.js 14+\n- Git repository\n- One of: npm, yarn, or pnpm\n\n## Contributing\n\nThis tool is designed to be simple and focused. If you have ideas for improvements, please open an issue to discuss before implementing major changes.\n\n## License\n\nMIT\n\n## Caveats\n\nThis tool was mostly written by Cursor and Claude 4 Sonnet.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatico%2Flockfile-guardian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatico%2Flockfile-guardian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatico%2Flockfile-guardian/lists"}