lockfile-guardian

🔒 Lockfile Guardian

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.

The Problem

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

The Solution

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

Features

• 🎯 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

Quick Start

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

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

How It Works

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

Husky Compatibility

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

✅ What Works

• 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

🔧 How It Works

# 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

🚀 Setup with Husky

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

📋 Example Integration

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

Configuration

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)
  }
}

Commands

# 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

Supported Package Managers

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)

Example Output

Basic Warning

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

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

With Auto-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!

What Gets Created

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.

Safety Features

• 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

Why Use This?

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

Comparison with Alternatives

Tool	Setup	Auto-install	Zero deps	Git integrated	Husky compatible
Lockfile Guardian	✅ One command	✅ Optional	✅ Yes	✅ Native hooks	✅ Yes
@antfu/ni	❌ Manual usage	❌ Manual	❌ No	❌ No	❌ No
Manual git hooks	❌ Complex setup	❌ Script required	✅ Yes	✅ Yes	⚠️ Manual
IDE extensions	❌ Per-editor setup	❌ Usually not	❌ No	❌ No	❌ No

Requirements

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

Contributing

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.

License

MIT

Caveats

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