npm package: @scaffit/husky
Description: Husky Git hooks setup with lint-staged for Next.js, React, Vue, Angular, Svelte, Express, Fastify, Node.js projects
Author: Santosh Hanumaiah Ranganatha
Latest version: 1.0.4

# @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)
```bash
# Add Husky scaffold (no installation needed!)
npx scaffit add husky
```

### Alternative: Global Installation
```bash
# Install CLI globally
npm install -g scaffit

# Add Husky scaffold
scaffit add husky
```

### Option 2: Direct npm package usage
```bash
# 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:

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

npx lint-staged
```

### .husky/pre-push
Pre-push hook that runs tests:

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

npm run test
```

### .lintstagedrc.json
Framework-specific lint-staged configuration:

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

**React/Vue/Angular/Svelte:**
```json
{
  "*.{js,jsx,ts,tsx,vue}": [
    "eslint --fix",
    "prettier --write"
  ],
  "*.{json,md,yml,yaml}": [
    "prettier --write"
  ]
}
```

**Express/Fastify/Node.js:**
```json
{
  "*.{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
```bash
# Run pre-commit hook manually
npx husky run pre-commit

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

### Skip hooks temporarily
```bash
# 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:

```json
{
  "*.{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

```bash
# 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