Husky

Ultracite provides seamless integration with Husky, a popular tool for managing Git hooks. This integration automatically sets up pre-commit hooks to ensure your code is properly formatted before every commit.

What is Husky?

Husky is a tool that makes it easy to use Git hooks in your project. Git hooks are scripts that run automatically at certain points in the Git workflow, such as before committing or pushing code. Husky simplifies the process of setting up and managing these hooks.

How Ultracite Uses Husky

When you initialize Ultracite in your project, it can automatically configure Husky to run code formatting before each commit. This ensures that:

• All committed code follows consistent formatting standards
• Code quality checks are enforced automatically
• Team members don't need to remember to format code manually
• Your repository maintains clean, consistent code style

Pre-commit Hook Behavior

Ultracite's Husky integration creates a pre-commit hook that runs the following command:

npx ultracite format

This command:

• Runs Biome's linter and formatter on your codebase
• Automatically fixes formatting issues where possible
• Ensures all staged files meet your project's code standards
• Prevents commits that would introduce formatting inconsistencies

Automatic Setup

During the initialization process (ultracite init), if you select the Husky option, Ultracite:

1. Installs Husky: Adds Husky as a development dependency to your project
2. Creates Hook File: Sets up the .husky/pre-commit file with the formatting command
3. Handles Existing Setups: If you already have Husky configured, it updates your existing pre-commit hook rather than overwriting it

Integration Details

The Husky integration includes several smart features:

Dependency Management

• Automatically installs Husky as a dev dependency using your project's package manager
• Uses the appropriate package manager command (npm install -D, yarn add -D, pnpm add -D, etc.)

Hook Management

• New Projects: Creates a new .husky/pre-commit file with the Ultracite format command
• Existing Projects: Appends the Ultracite command to your existing pre-commit hook, preserving other hooks you may have configured

File Structure

The integration creates or modifies:

.husky/
└── pre-commit    # Contains the formatting command

Benefits

Consistent Code Style

Every commit automatically follows your project's formatting standards, eliminating style debates and inconsistencies.

Automated Quality Control

Catch formatting issues before they enter your repository, maintaining clean commit history.

Team Collaboration

All team members automatically follow the same formatting standards without manual intervention.

CI/CD Optimization

Reduce CI/CD pipeline failures due to formatting issues, as code is pre-formatted locally.

Workflow Integration

With Husky integration enabled, your typical Git workflow becomes:

1. Make changes to your code files
2. Stage changes with git add
3. Commit changes with git commit
4. Pre-commit hook runs automatically, formatting staged files
5. Commit proceeds with properly formatted code

If the formatter makes changes, you'll need to stage and commit those changes as well.

Customization

While Ultracite sets up sensible defaults, you can customize the behavior:

• Modify .husky/pre-commit to add additional commands
• Configure Biome settings to adjust formatting rules
• Add other pre-commit checks alongside Ultracite's formatting

Troubleshooting

Hook Not Running

If the pre-commit hook isn't executing:

• Ensure Husky is installed: npm ls husky
• Check that .husky/pre-commit exists and is executable
• Verify Git hooks are enabled in your repository

Permission Issues

On Unix-like systems, ensure the hook file is executable:

chmod +x .husky/pre-commit

Bypassing Hooks

In rare cases where you need to skip the pre-commit hook:

git commit --no-verify

Use this sparingly, as it bypasses the automated formatting that keeps your codebase consistent.