MW Husky Config

A reusable Husky configuration package for maintaining consistent Git hooks across multiple projects with automated setup.

npm i --save-dev @mediusware/mw-husky-config

Features

• Automated Installation: One command setup with dependency installation and configuration

• Pre-commit Hook: Runs code quality checks including:

  • Prettier formatting
  • ESLint code linting
  • Spelling checks (cspell)
  • Secret scanning (secretlint)
  • Security audit (npm audit)

• Commit Message Hook: Enforces conventional commit standards

  • Validates commit message format
  • Ensures proper commit types (feat, fix, chore, etc.)
  • Validates message length (10-100 characters)

Installation

1. Install the package

npm install --save-dev @mediusware/mw-husky-config

2. Choose Your Installation Mode

Simple options (recommended):

# JavaScript / Node project (pre-commit + commit-msg + security)
npx install-husky --javascript
# or: npx install-husky --js

# PHP / Laravel project (commit-msg + Pint, PHPStan)
npx install-husky --php
# or: npx install-husky --laravel

Other modes: --full-setup, --only-style-commit-msg, --only-commit-msg (see below).

Full Setup (Default)

Complete setup with all features (same as --javascript):

npx install-husky
# or explicitly:
npx install-husky --full-setup
npx install-husky --javascript

Includes:

• Pre-commit hooks (formatting, linting, spelling)
• Security checks (secret scanning, npm audit)
• Commit message validation
• Commit message template

Dependencies: husky, lint-staged, prettier, eslint, cspell, secretlint, @secretlint/secretlint-rule-preset-recommend

Style & Commit Message Only

For projects that want code quality checks without security scanning:

npx install-husky --only-style-commit-msg

Includes:

• Pre-commit hooks (formatting, linting, spelling)
• Commit message validation
• Commit message template
• No security checks

Dependencies: husky, lint-staged, prettier, eslint, cspell

Commit Message Only

Minimal setup - only enforces commit message standards:

npx install-husky --only-commit-msg

Includes:

• Commit message validation
• Commit message template
• No pre-commit style checks
• No security checks

Dependencies: husky only

Laravel / PHP

For Laravel projects: commit message validation + PHP pre-commit (Pint, PHPStan). No JS spelling/lint/secret checks.

npx install-husky --php
# or: npx install-husky --laravel

Includes:

• Commit message validation (conventional commits)
• Pre-commit: Laravel Pint, PHPStan (via Composer)
• Commit message template
• No cspell, ESLint, Prettier, or secretlint

Dependencies: husky only (npm). PHP tools via Composer: laravel/pint, phpstan/phpstan.

Composer scripts (added automatically if missing):

• lint – vendor/bin/pint
• analyse – vendor/bin/phpstan

3. Non-interactive mode

For CI/CD or automated setups, use the --yes flag with any mode:

npx install-husky --javascript --yes   # or --php --yes, --only-commit-msg --yes, etc.

This will automatically accept all prompts and complete the setup.

4. Mode Comparison

| Feature | Full Setup | Style & Commit Msg | Commit Msg Only | Laravel | |---------|------------|-------------------|-----------------|---------| | Commit message validation | Yes | Yes | Yes | Yes | | Pre-commit (JS: prettier, eslint, cspell) | Yes | Yes | No | No | | Pre-commit (PHP: pint, phpstan) | No | No | No | Yes | | Secret scanning | Yes | No | No | No | | npm audit | Yes | No | No | No | | Dependencies (npm) | 7 packages | 5 packages | 1 package | 1 package |

SOC 2 and compliance

Full-setup mode supports SOC 2–relevant controls: secret scanning (confidentiality), traceable commits (change management), code quality checks, and dependency audit. Use full-setup for strongest coverage. See docs/SOC2-COMPLIANCE.md for a control mapping and optional hardening (e.g. failing on npm audit, signed commits).

What Gets Automated

The installer automatically handles (varies by mode):

Dependency Installation

• Installs only the dependencies needed for your chosen mode
• Prompts before installing (skip with --yes)

Package.json Configuration

• Adds required scripts based on mode
• Configures lint-staged with file patterns (if applicable)
• Adds prepare script for Husky initialization

Git Hooks Setup

• Copies appropriate hooks for your mode
• Makes hooks executable (Unix-based systems)
• Sets up commit message template

Git Configuration

• Configures commit.template to use .gitmessage

Usage Examples

Example 1: JavaScript / Full Setup (Enterprise)

cd my-enterprise-app
npm install --save-dev @mediusware/mw-husky-config
npx install-husky --javascript --yes

Result: Complete setup with all security and quality checks.

Example 2: Open Source Project (No Security Scanning)

cd my-open-source-lib
npm install --save-dev @mediusware/mw-husky-config
npx install-husky --only-style-commit-msg

Result: Code quality checks without secret scanning (good for public repos).

Example 3: Simple Documentation Repo

cd my-docs-repo
npm install --save-dev @mediusware/mw-husky-config
npx install-husky --only-commit-msg --yes

Result: Only commit message validation, no code checks.

Example 4: Laravel / PHP Project

cd my-laravel-app
npm install --save-dev @mediusware/mw-husky-config
npx install-husky --php --yes

Result: Commit message validation + pre-commit running Pint and PHPStan. Install PHP tools if needed: composer require --dev laravel/pint phpstan/phpstan.

Manual Configuration (Optional)

If you skip the automated setup, you can manually add to your package.json:

{
  "scripts": {
    "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,css,md}\"",
    "lint:fix": "eslint --fix",
    "spell": "cspell \"**/*.{js,jsx,ts,tsx,md,json}\" --no-progress",
    "security:secrets": "secretlint \"**/*\"",
    "security": "npm audit --audit-level=moderate",
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "prettier --write",
      "eslint --fix",
      "cspell --no-must-find-files"
    ],
    "*.{json,css,md}": [
      "prettier --write",
      "cspell --no-must-find-files"
    ]
  }
}

Command Reference

# Simple options (recommended)
npx install-husky --javascript          # JS/Node: full pre-commit + commit-msg + security
npx install-husky --js --yes           # same, non-interactive
npx install-husky --php                # PHP/Laravel: commit-msg + Pint, PHPStan
npx install-husky --laravel --yes      # same, non-interactive

# Default full setup (interactive)
npx install-husky

# Full setup (non-interactive)
npx install-husky --full-setup --yes

# Style checks + commit message (interactive)
npx install-husky --only-style-commit-msg

# Style checks + commit message (non-interactive)
npx install-husky --only-style-commit-msg --yes

# Commit message only (interactive)
npx install-husky --only-commit-msg

# Commit message only (non-interactive)
npx install-husky --only-commit-msg --yes

# Laravel / PHP (commit-msg + PHP pre-commit)
npx install-husky --php
npx install-husky --laravel --yes

Configuration Files

Automatically Created Configurations

The installer creates default configuration files based on your selected mode:

CSpell Configuration (.cspell.json)

Created for: --full-setup and --only-style-commit-msg modes

Default configuration includes:

• Common dev tool names (husky, eslint, prettier, etc.)
• Ignored paths (node_modules, dist, build)
• Ignored patterns (hex codes, UUIDs, all-caps abbreviations)
• Compound word support

You can customize this file to:

• Add project-specific words to the words array
• Ignore additional paths or patterns
• Configure language settings

See cspell documentation for all options.

Secretlint Configuration (.secretlintrc.json)

Created for: --full-setup mode only

Default configuration scans for:

• API keys and tokens
• Private keys and certificates
• AWS credentials
• Database connection strings
• Other sensitive data

You can customize this file to add or remove rules. See secretlint documentation for available rules.

Additional Configurations (Optional)

You may also want to configure:

• .prettierrc - Prettier formatting rules
• .eslintrc - ESLint linting rules

Customization

After installation, you can customize the hooks in your project's .husky/ directory to match your specific requirements.

Pre-commit Hook Customization

Edit .husky/pre-commit to:

• Add or remove quality checks
• Modify validation rules
• Change error messages

Commit Message Hook Customization

Edit .husky/commit-msg to:

• Add or remove commit types
• Change message length limits
• Modify validation regex patterns

Commit Message Format

This configuration enforces the following commit message format:

<type>: <description>

Supported Types

• feat: New feature
• fix: Bug fix
• chore: Routine task
• hotfix: Urgent fix
• refactor: Code refactoring
• docs: Documentation changes
• test: Testing changes
• ci: CI/CD changes
• perf: Performance improvements

Examples

git commit -m "feat: add user authentication system"
git commit -m "fix: resolve database connection timeout"
git commit -m "chore: update npm dependencies"
git commit -m "refactor: simplify payment processing logic"

Requirements

• Node.js >= 14.0.0
• npm >= 6.0.0
• Git >= 2.9.0
• Husky >= 9.0.0

Troubleshooting

Hooks not running

1. Ensure Husky is properly initialized:

   npx husky install

2. Check that hooks are executable (Unix-based systems):

   chmod +x .husky/*

3. Verify the prepare script is in your package.json:

   {
     "scripts": {
       "prepare": "husky"
     }
   }

Permission errors on Windows

Hooks should work on Windows via Git Bash or WSL. If you encounter issues:

• Use Git Bash instead of PowerShell/CMD
• Or install Windows Subsystem for Linux (WSL)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Author

Mediusware Engineering Team

Links

• Husky Documentation
• Conventional Commits
• lint-staged