🐕 Husky: Git Hooks Integration

🎯 Introduction

Welcome to the exciting world of Git hooks with Husky! 🎉 In this guide, we’ll explore how to automate your development workflow and catch issues before they reach your repository.

You’ll discover how Husky can transform your TypeScript development experience by automatically running tests 🧪, linters 🔍, and type checks ✅ every time you make a commit. Whether you’re working solo or with a team 👥, understanding Husky is essential for maintaining code quality and preventing bugs from sneaking into your codebase.

By the end of this tutorial, you’ll feel confident setting up robust pre-commit workflows in your TypeScript projects! Let’s dive in! 🏊‍♂️

📚 Understanding Git Hooks and Husky

🤔 What are Git Hooks?

Git hooks are like automated security guards 🛡️ for your repository. Think of them as checkpoints at an airport ✈️ that ensure everything is safe before letting you board (or in this case, commit your code).

In Git terms, hooks are scripts that run automatically at specific points in your Git workflow 🔄. This means you can:

• ✨ Run tests before every commit
• 🚀 Check code formatting automatically
• 🛡️ Prevent bad code from entering your repository
• 📝 Enforce commit message standards

💡 What is Husky?

Husky is like a friendly dog trainer 🐕 that makes managing Git hooks super easy! Instead of dealing with complex shell scripts hidden in .git/hooks, Husky lets you:

1. Easy Setup 🔧: Configure hooks with simple npm commands
2. Version Control 📦: Keep your hooks in your repository
3. Team Sharing 👥: Everyone gets the same quality checks
4. TypeScript Integration 💙: Perfect for TypeScript projects

Real-world example: Imagine working on a team project 👨‍💻👩‍💻. With Husky, every developer automatically runs the same linting and testing checks before committing, ensuring consistent code quality!

🔧 Basic Installation and Setup

📦 Installing Husky

Let’s start with a friendly setup process:

# 🚀 Install husky as a dev dependency
npm install --save-dev husky

# 🎯 Initialize husky in your project
npx husky install

# ✨ Make husky installation automatic for new contributors
npm pkg set scripts.prepare="husky install"

💡 Explanation: The prepare script ensures husky gets set up automatically when someone runs npm install on your project!

🎨 Project Structure

After installation, your project will look like this:

your-project/
├── .husky/          # 🐕 Husky configuration folder
│   ├── _/          # 📁 Husky internal files
│   └── pre-commit  # 🎯 Pre-commit hook (we'll create this)
├── package.json     # 📦 Dependencies and scripts
└── src/            # 💻 Your TypeScript code

🎯 Your First Hook

Let’s create a simple pre-commit hook:

# 🛠️ Create a pre-commit hook that runs TypeScript checks
npx husky add .husky/pre-commit "npm run typecheck"

This creates a file at .husky/pre-commit that looks like:

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

npm run typecheck

💡 Practical Examples

🛒 Example 1: E-commerce TypeScript Project

Let’s set up comprehensive quality checks for an online store:

// 🏪 Our e-commerce types
interface Product {
  id: string;
  name: string;
  price: number;
  category: 'electronics' | 'clothing' | 'books';
  inStock: boolean;
  emoji: string; // Every product needs personality! 
}

interface ShoppingCart {
  id: string;
  items: CartItem[];
  total: number;
  customerEmail: string;
}

interface CartItem {
  product: Product;
  quantity: number;
}

// 🛍️ Shopping cart service
class CartService {
  private carts: Map<string, ShoppingCart> = new Map();
  
  // ➕ Add item to cart
  addToCart(cartId: string, product: Product, quantity: number): void {
    const cart = this.carts.get(cartId);
    if (!cart) {
      throw new Error(`🚫 Cart ${cartId} not found!`);
    }
    
    if (!product.inStock) {
      throw new Error(`📦 ${product.name} is out of stock!`);
    }
    
    const existingItem = cart.items.find(item => item.product.id === product.id);
    if (existingItem) {
      existingItem.quantity += quantity;
    } else {
      cart.items.push({ product, quantity });
    }
    
    this.updateTotal(cart);
    console.log(`✅ Added ${product.emoji} ${product.name} to cart!`);
  }
  
  // 💰 Calculate total
  private updateTotal(cart: ShoppingCart): void {
    cart.total = cart.items.reduce((sum, item) => 
      sum + (item.product.price * item.quantity), 0
    );
  }
}

package.json scripts for this project:

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "lint": "eslint src/**/*.ts",
    "format": "prettier --write src/**/*.ts",
    "test": "jest",
    "build": "tsc"
  }
}

🐕 Husky hooks setup:

# 🎯 Pre-commit: Run all quality checks
npx husky add .husky/pre-commit "npm run lint && npm run typecheck && npm run test"

# 🚀 Pre-push: Ensure build works
npx husky add .husky/pre-push "npm run build"

# 📝 Commit message validation
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

🎮 Example 2: Game Development Project

Let’s make our game development workflow bulletproof:

// 🎯 Game state management
interface GameState {
  player: Player;
  enemies: Enemy[];
  score: number;
  level: number;
  powerUps: PowerUp[];
}

interface Player {
  id: string;
  name: string;
  health: number;
  position: Position;
  inventory: Item[];
  emoji: string;
}

interface Enemy {
  id: string;
  type: 'goblin' | 'dragon' | 'skeleton';
  health: number;
  damage: number;
  position: Position;
  emoji: string;
}

interface Position {
  x: number;
  y: number;
}

// 🎮 Game engine
class GameEngine {
  private state: GameState;
  
  constructor(playerName: string) {
    this.state = {
      player: {
        id: 'player1',
        name: playerName,
        health: 100,
        position: { x: 0, y: 0 },
        inventory: [],
        emoji: '🧙‍♂️'
      },
      enemies: [],
      score: 0,
      level: 1,
      powerUps: []
    };
  }
  
  // ⚔️ Battle logic
  attack(targetId: string): boolean {
    const enemy = this.state.enemies.find(e => e.id === targetId);
    if (!enemy) {
      console.log('🚫 Enemy not found!');
      return false;
    }
    
    const damage = Math.floor(Math.random() * 20) + 10;
    enemy.health -= damage;
    console.log(`⚔️ Hit ${enemy.emoji} for ${damage} damage!`);
    
    if (enemy.health <= 0) {
      this.defeatEnemy(enemy);
      return true;
    }
    
    return false;
  }
  
  // 🏆 Victory!
  private defeatEnemy(enemy: Enemy): void {
    this.state.enemies = this.state.enemies.filter(e => e.id !== enemy.id);
    this.state.score += 100;
    console.log(`🎉 Defeated ${enemy.emoji}! Score: ${this.state.score}`);
  }
}

🔧 Advanced Husky Configuration:

# 🧪 Run specific tests for game files
npx husky add .husky/pre-commit "npm run test:game && npm run lint:strict"

# 🎨 Auto-format game assets
npx husky add .husky/pre-commit "npm run format:assets"

# 🏗️ Build and test game bundle
npx husky add .husky/pre-push "npm run build:game && npm run test:integration"

🚀 Advanced Husky Configurations

🧙‍♂️ Conditional Hooks with lint-staged

For better performance, only check changed files:

# 📦 Install lint-staged
npm install --save-dev lint-staged

package.json configuration:

{
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write",
      "tsc --noEmit"
    ],
    "*.{json,md}": [
      "prettier --write"
    ]
  },
  "scripts": {
    "pre-commit": "lint-staged"
  }
}

🐕 Updated husky hook:

# ⚡ Only check changed files (much faster!)
npx husky add .husky/pre-commit "npm run pre-commit"

🏗️ Complex Workflow Example

For enterprise projects with multiple checks:

// 🏢 Enterprise configuration types
interface HuskyConfig {
  hooks: {
    'pre-commit': string[];
    'pre-push': string[];
    'commit-msg': string[];
  };
  lintStaged: {
    [pattern: string]: string[];
  };
  commitlint: {
    extends: string[];
    rules: Record<string, any>;
  };
}

// 📋 Configuration factory
class HuskyConfigFactory {
  static createTypeScriptConfig(): HuskyConfig {
    return {
      hooks: {
        'pre-commit': [
          'lint-staged',
          'npm run test:unit',
          'npm run typecheck'
        ],
        'pre-push': [
          'npm run test:integration',
          'npm run build',
          'npm run security-check'
        ],
        'commit-msg': [
          'commitlint --edit $1'
        ]
      },
      lintStaged: {
        '*.{ts,tsx}': [
          'eslint --fix',
          'prettier --write',
          'tsc --noEmit'
        ],
        '*.{json,md,yml}': [
          'prettier --write'
        ]
      },
      commitlint: {
        extends: ['@commitlint/config-conventional'],
        rules: {
          'type-enum': [2, 'always', [
            'feat', 'fix', 'docs', 'style', 'refactor', 
            'test', 'chore', 'perf', 'ci', 'build'
          ]]
        }
      }
    };
  }
}

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Hooks Not Running

# ❌ Wrong - forgetting to install husky
git commit -m "my commit"
# No checks run! 😰

# ✅ Correct - ensure husky is installed
npm run prepare  # This runs 'husky install'
git commit -m "feat: add awesome feature ✨"
# 🎉 All checks run!

🤯 Pitfall 2: Slow Pre-commit Hooks

# ❌ Slow - checking entire codebase
npx husky add .husky/pre-commit "npm run lint && npm run test"

# ✅ Fast - only check changed files
npx husky add .husky/pre-commit "lint-staged"

📋 lint-staged config:

{
  "lint-staged": {
    "*.ts": ["eslint --fix", "prettier --write"]
  }
}

🚫 Pitfall 3: Broken Hooks Stop Development

# 🛡️ Add escape hatch for emergencies
git commit --no-verify -m "hotfix: critical bug fix"

⚠️ Warning: Only use --no-verify in genuine emergencies!

🛠️ Best Practices

1. 🎯 Keep Hooks Fast: Use lint-staged for speed
2. 📝 Document Your Hooks: Explain what each hook does
3. 🛡️ Don’t Block Everything: Allow emergency commits
4. 🎨 Make Hooks Helpful: Auto-fix issues when possible
5. ✨ Test Your Hooks: Ensure they work in different scenarios
6. 👥 Team Communication: Explain hooks to new team members

🎨 Example Documentation

# 🐕 Our Husky Setup

## Pre-commit Hooks
- ✅ TypeScript type checking
- 🎨 ESLint with auto-fix
- 📝 Prettier code formatting
- 🧪 Unit tests for changed files

## Pre-push Hooks  
- 🏗️ Full build test
- 🔒 Security vulnerability scan
- 📊 Bundle size check

## Emergency Override
Use `git commit --no-verify` only for critical hotfixes! 🚨

🧪 Hands-On Exercise

🎯 Challenge: Set Up a Complete Husky Workflow

Create a robust development workflow for a TypeScript project:

📋 Requirements:

• ✅ Pre-commit: Lint, format, and type-check changed files
• 🧪 Pre-commit: Run relevant tests
• 🏗️ Pre-push: Ensure the project builds
• 📝 Commit message: Enforce conventional commits
• 🚀 Only process changed files for speed

🎮 Bonus Points:

• Add a commit message emoji guide
• Create a security check hook
• Set up automatic dependency updates validation
• Add a hook to check bundle size

💡 Solution

# 🚀 Complete setup script!

# 1. Install dependencies
npm install --save-dev husky lint-staged @commitlint/cli @commitlint/config-conventional

# 2. Initialize husky
npx husky install
npm pkg set scripts.prepare="husky install"

# 3. Create pre-commit hook
npx husky add .husky/pre-commit "lint-staged"

# 4. Create pre-push hook
npx husky add .husky/pre-push "npm run build && npm run test:integration"

# 5. Create commit message hook
npx husky add .husky/commit-msg "npx --no -- commitlint --edit \$1"

{
  "scripts": {
    "prepare": "husky install",
    "typecheck": "tsc --noEmit",
    "lint": "eslint src/**/*.{ts,tsx}",
    "lint:fix": "eslint src/**/*.{ts,tsx} --fix",
    "format": "prettier --write src/**/*.{ts,tsx,json,md}",
    "test": "jest",
    "test:integration": "jest --config=jest.integration.config.js",
    "build": "tsc && vite build",
    "bundle-size": "bundlesize"
  },
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write",
      "tsc --noEmit"
    ],
    "*.{json,md}": [
      "prettier --write"
    ]
  },
  "commitlint": {
    "extends": ["@commitlint/config-conventional"],
    "rules": {
      "type-enum": [2, "always", [
        "feat", "fix", "docs", "style", "refactor",
        "test", "chore", "perf", "ci", "build"
      ]],
      "subject-case": [2, "always", "sentence-case"]
    }
  },
  "bundlesize": [
    {
      "path": "./dist/bundle.js",
      "maxSize": "100kb"
    }
  ]
}

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

echo "🏗️ Building project..."
npm run build

echo "🧪 Running integration tests..."
npm run test:integration

echo "🔒 Checking for security vulnerabilities..."
npm audit --audit-level high

echo "📦 Checking bundle size..."
npm run bundle-size

echo "✅ All pre-push checks passed! 🎉"

# 📝 Commit Message Guide

Use this format: `type(scope): description`

## Types
- feat ✨: New feature
- fix 🐛: Bug fix  
- docs 📚: Documentation
- style 🎨: Code style changes
- refactor ♻️: Code refactoring
- test 🧪: Adding tests
- chore 🔧: Maintenance tasks

## Examples
- `feat(auth): add user login 🔐`
- `fix(cart): resolve checkout bug 🛒`
- `docs(readme): update installation guide 📖`

🎓 Key Takeaways

You’ve learned so much about Husky and Git hooks! Here’s what you can now do:

• ✅ Set up Husky in any TypeScript project 💪
• ✅ Create pre-commit workflows that catch issues early 🛡️
• ✅ Optimize hook performance with lint-staged 🚀
• ✅ Enforce code quality across your entire team 🎯
• ✅ Debug common hook issues like a pro 🐛
• ✅ Build bulletproof development workflows ⚔️

Remember: Husky is your development assistant, not your enemy! It’s here to help you ship better code faster. 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered Git hooks with Husky!

Here’s what to do next:

1. 💻 Set up Husky in your current TypeScript project
2. 🏗️ Create a comprehensive pre-commit workflow
3. 📚 Move on to our next tutorial: ESLint with TypeScript
4. 🌟 Share your Husky setup with your team!

Remember: Every smooth deployment started with good development practices. Keep automating, keep improving, and most importantly, keep coding! 🚀

Happy coding! 🎉🐕✨