Never 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.

You know this scenario:

• Teammate adds a new dependency
• You git pull or switch branches
• Your code breaks because you forgot to run npm install
• You spend 10 minutes debugging before realizing the issue

Lockfile Guardian installs git hooks that automatically detect when your lock files have changed and either warn you or auto-install dependencies.

• 🎯 Zero runtime dependencies - Pure Node.js implementation
• 🔍 Smart detection - Auto-detects npm, yarn, or pnpm lock files
• ⚡ One-command setup - npx lockfile-guardian install and you're done
• 🪝 Git hooks - Works on checkout, pull, merge, and branch switching
• 🔧 Configurable - Optional auto-install and silent modes
• 📦 TypeScript - Built with TypeScript, works with any Node.js project
• 🧹 Clean - Stores metadata in .git/ directory, not your working tree
• ⚠️ Visual warnings - Eye-catching alerts when dependencies are out of sync
• 🐶 Husky compatible - Works seamlessly with Husky, lint-staged, prettier, and other tools

# Install and setup git hooks (one time only)
npx lockfile-guardian install

# That's it! Now every git operation checks your dependencies

1. Secure tracking - Stores SHA256 hash of your lock file in .git/lockfile-guardian
2. Git integration - Installs hooks for post-checkout, post-merge, and post-rewrite
3. Smart detection - Automatically finds and monitors the right lock file
4. Helpful warnings - Shows exactly which command to run for your package manager
5. Optional automation - Can automatically install dependencies if configured

Lockfile Guardian is fully compatible with Husky and works seamlessly alongside other tools:

• Husky v4+ - Automatically detects and uses .husky/ directory
• lint-staged - Runs after linting and formatting tools
• prettier - Compatible with prettier hooks
• ESLint - Works with ESLint pre-commit hooks
• Traditional hooks - Falls back to .git/hooks/ when Husky isn't detected

# Your existing .husky/pre-commit
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged

# After installing lockfile-guardian, your .husky/post-checkout becomes:
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# Your existing hooks run first...

# Lockfile Guardian
npx lockfile-guardian check --hook

If you're already using Husky, just install normally:

npx lockfile-guardian install

Lockfile Guardian will:

• ✅ Detect your Husky setup automatically
• ✅ Install hooks in .husky/ directory
• ✅ Preserve all existing hook configurations
• ✅ Run after your other tools (lint-staged, prettier, etc.)

{
  "scripts": {
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{js,ts,tsx}": ["prettier --write", "eslint --fix"],
    "*.{json,md}": ["prettier --write"]
  },
  "lockfileGuardian": {
    "autoInstall": true,
    "silent": false
  }
}

Add optional configuration to your package.json:

{
  "lockfileGuardian": {
    "autoInstall": true, // Automatically run install commands
    "silent": false, // Suppress non-warning output
    "checkNodeModules": true // Warn if node_modules isn't gitignored (default: true)
  }
}

# Setup git hooks (one-time setup)
npx lockfile-guardian install

# Remove all hooks and cleanup
npx lockfile-guardian uninstall

# Manually check for lock file changes
npx lockfile-guardian check

# Show help and current configuration
npx lockfile-guardian

Automatically detects and supports:

• pnpm - pnpm-lock.yaml → pnpm install
• Yarn - yarn.lock → yarn install
• npm - package-lock.json → npm install

Detection priority: pnpm → yarn → npm (first lock file found wins)

$ git checkout feature/new-deps
=====================================
⚠️  DEPENDENCIES OUT OF DATE  ⚠️
=====================================
Lock file pnpm-lock.yaml has changed!

Run this command to update:
  pnpm install
=====================================

$ git pull origin main
🔒 Lock file yarn.lock has changed!
🔒 Auto-installing dependencies with yarn...
yarn install v1.22.19
[1/4] 🔍  Resolving packages...
[2/4] 🚚  Fetching packages...
[3/4] 🔗  Linking dependencies...
[4/4] 🔨  Building fresh packages...
✨ Done in 2.34s.
🔒 Dependencies updated successfully!

Git hooks:

• .git/hooks/post-checkout - Runs after branch switching
• .git/hooks/post-merge - Runs after git pull/git merge
• .git/hooks/post-rewrite - Runs after git rebase

Metadata:

• .git/lockfile-guardian - Stores hash of current lock file

Nothing in your working directory! All tool data stays in .git/ where it belongs.

• Non-destructive - Only reads lock files, never modifies them
• Git validation - Ensures you're in a git repository before installing
• Gitignore check - Warns if node_modules isn't properly ignored
• Safe uninstall - Completely removes all traces when uninstalled
• Error handling - Graceful failure if install commands fail

For individuals:

• Never waste time debugging dependency issues again
• Automatic detection works seamlessly in the background
• Zero maintenance after initial setup

For teams:

• Ensures everyone has the same dependencies installed
• Prevents "works on my machine" issues
• Catches dependency updates immediately after pulling changes
• Reduces onboarding friction for new team members

• Node.js 14+
• Git repository
• One of: npm, yarn, or pnpm

This tool is designed to be simple and focused. If you have ideas for improvements, please open an issue to discuss before implementing major changes.

MIT

This tool was mostly written by Cursor and Claude 4 Sonnet.