@scaffit/husky

Husky Git hooks setup with lint-staged for automated code quality.

Features

• Multi-framework support - Next.js, React, Vue, Angular, Svelte, Express, Fastify, Node.js
• Automatic framework detection - Adapts hooks based on your project
• Pre-commit hooks - Run linting and formatting before commits
• Pre-push hooks - Run tests before pushing
• Lint-staged integration - Only lint staged files for performance
• Customizable hooks - Choose which hooks to enable
• Framework-specific configurations - Optimized for each framework

Installation

Option 1: Using Scaffit CLI (Recommended)

# Add Husky scaffold (no installation needed!)
npx scaffit add husky

Alternative: Global Installation

# Install CLI globally
npm install -g scaffit

# Add Husky scaffold
scaffit add husky

Option 2: Direct npm package usage

# Install scaffold directly
npm install @scaffit/husky

# Use in your code
import { setupHusky, previewHusky } from '@scaffit/husky';

// Setup Husky with custom options
const result = await setupHusky({
  enablePreCommit: true,
  enablePrePush: true,
  enableCommitMsg: false,
  projectRoot: './my-project'
});

// Preview changes before applying
const preview = await previewHusky({
  enablePreCommit: true,
  enablePrePush: true
});

Note: Both approaches require @scaffit/core to be installed (automatically handled).

Configuration Options

• Pre-commit hooks: Run linting and formatting on staged files
• Pre-push hooks: Run tests before pushing
• Lint-staged: Enable lint-staged for performance
• Framework: Automatically detected (Next.js, React, Vue, Angular, Svelte, Express, Fastify, Node.js)

Generated Files

.husky/pre-commit

Pre-commit hook that runs lint-staged:

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

npx lint-staged

.husky/pre-push

Pre-push hook that runs tests:

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

npm run test

.lintstagedrc.json

Framework-specific lint-staged configuration:

Next.js:

{
  "*.{js,jsx,ts,tsx}": [
    "eslint --fix",
    "prettier --write"
  ],
  "*.{json,md,yml,yaml}": [
    "prettier --write"
  ]
}

React/Vue/Angular/Svelte:

{
  "*.{js,jsx,ts,tsx,vue}": [
    "eslint --fix",
    "prettier --write"
  ],
  "*.{json,md,yml,yaml}": [
    "prettier --write"
  ]
}

Express/Fastify/Node.js:

{
  "*.{js,ts}": [
    "eslint --fix",
    "prettier --write"
  ],
  "*.{json,md,yml,yaml}": [
    "prettier --write"
  ]
}

Dependencies Added

• husky - Git hooks made easy
• lint-staged - Run linters on staged files

Package.json Scripts Added

• prepare - Install Husky hooks (runs automatically after npm install)

Framework-Specific Features

Next.js

• Next.js specific file patterns
• TypeScript and JSX support
• Next.js best practices

React

• React component linting
• JSX file support
• React-specific patterns

Vue

• Vue component support
• Vue-specific file patterns
• Vue best practices

Angular

• Angular component support
• Angular-specific patterns
• Angular CLI compatibility

Svelte

• Svelte component support
• SvelteKit compatibility
• Svelte-specific patterns

Express/Fastify/Node.js

• Node.js specific patterns
• Server-side file support
• Node.js best practices

Usage Examples

Manual hook execution

# Run pre-commit hook manually
npx husky run pre-commit

# Run pre-push hook manually
npx husky run pre-push

Skip hooks temporarily

# Skip pre-commit hook
git commit --no-verify -m "commit message"

# Skip pre-push hook
git push --no-verify

Customize lint-staged

Edit .lintstagedrc.json to customize which files are processed:

{
  "*.{js,ts}": [
    "eslint --fix",
    "prettier --write"
  ],
  "*.{css,scss}": [
    "prettier --write"
  ],
  "*.{json,md}": [
    "prettier --write"
  ]
}

Hook Types

Pre-commit

• Runs before each commit
• Processes staged files only
• Prevents bad code from being committed
• Fast execution with lint-staged

Pre-push

• Runs before pushing to remote
• Runs full test suite
• Ensures code quality before sharing
• Can be skipped with --no-verify

Configuration

Husky Configuration

Husky hooks are stored in .husky/ directory:

• .husky/pre-commit - Pre-commit hook
• .husky/pre-push - Pre-push hook
• .husky/_/husky.sh - Husky helper script

Lint-staged Configuration

Lint-staged configuration in .lintstagedrc.json:

• File patterns and their corresponding commands
• Framework-specific optimizations
• Performance-focused file processing

Troubleshooting

Common Issues

1. Hooks not running: Ensure Husky is properly installed
2. Permission errors: Check file permissions on hook files
3. Slow hooks: Optimize lint-staged configuration
4. Hook failures: Check individual tool configurations

Debugging

# Check Husky installation
npx husky --version

# Test lint-staged manually
npx lint-staged --verbose

# Check hook files
ls -la .husky/

Best Practices

1. Keep hooks fast: Use lint-staged for pre-commit
2. Fail fast: Stop on first error
3. Clear messages: Provide helpful error messages
4. Skip when needed: Allow bypassing hooks when necessary
5. Team consistency: Ensure all team members use same hooks

Integration

With ESLint

• Automatically fixes ESLint errors
• Prevents committing code with linting errors
• Integrates with ESLint configuration

With Prettier

• Automatically formats code
• Ensures consistent code style
• Works with Prettier configuration

With Tests

• Runs tests before pushing
• Prevents broken code from being shared
• Integrates with test frameworks

Next Steps

1. Customize .lintstagedrc.json for your needs
2. Add more hooks as needed (commit-msg, etc.)
3. Configure team-wide hook policies
4. Set up CI/CD to match local hooks
5. Monitor hook performance and optimize