Yorkie

Yorkie is a Git hooks management tool that provides an easy way to configure and manage Git hooks in JavaScript projects. It's a fork of husky with specific improvements for monorepo environments, prioritizing package.json files located next to .git directories and using a cleaner gitHooks configuration format.

Package Information

• Package Name: yorkie
• Package Type: npm
• Language: JavaScript (Node.js)
• Installation: npm install yorkie

Core Imports

Yorkie primarily works through npm lifecycle hooks and provides programmatic access to its core functions:

const installFrom = require('yorkie/src/install');
const uninstallFrom = require('yorkie/src/uninstall');

Utilities can be imported individually:

const findHooksDir = require('yorkie/src/utils/find-hooks-dir');
const findParent = require('yorkie/src/utils/find-parent');
const getHookScript = require('yorkie/src/utils/get-hook-script');
const { huskyOrYorkie, ghooks, preCommit } = require('yorkie/src/utils/is');

Basic Usage

Git Hooks Configuration

Configure Git hooks in your package.json using the gitHooks field:

{
  "name": "my-project",
  "scripts": {
    "test": "jest",
    "lint": "eslint ."
  },
  "gitHooks": {
    "pre-commit": "npm run lint",
    "pre-push": "npm test",
    "commit-msg": "commitizen --cz-conventional-changelog"
  },
  "devDependencies": {
    "yorkie": "^2.0.0"
  }
}

Automatic Installation

Yorkie automatically installs Git hooks when the package is installed:

npm install yorkie
# Git hooks are automatically set up during installation

Environment Variables

Control yorkie's behavior with environment variables:

# Skip installation in CI environments (overrides default CI detection)
export YORKIE_IGNORE_CI=1

# Skip installation entirely during npm install
export YORKIE_SKIP_INSTALL=1

# Legacy husky compatibility: skip installation in CI
export HUSKY_IGNORE_CI=1

# Legacy husky compatibility: skip installation entirely  
export HUSKY_SKIP_INSTALL=1

Environment Variable Behavior:

• CI Detection: Yorkie automatically detects CI environments using the is-ci package and skips installation by default
• Override CI: Set YORKIE_IGNORE_CI=1 or HUSKY_IGNORE_CI=1 to force installation in CI environments
• Skip Installation: Set YORKIE_SKIP_INSTALL=1 or HUSKY_SKIP_INSTALL=1 to completely bypass hook installation
• Legacy Support: Both HUSKY_* and YORKIE_* prefixed variables are supported for compatibility

Capabilities

Hook Installation

Automatically installs Git hooks for all supported hook types during npm package installation.

/**
 * Install Git hooks from a yorkie dependency directory
 * @param {string} depDir - Path to the yorkie dependency directory
 */
function installFrom(depDir);

Supported Git Hooks:

• applypatch-msg, pre-applypatch, post-applypatch
• pre-commit, prepare-commit-msg, commit-msg, post-commit
• pre-rebase, post-checkout, post-merge
• pre-push, pre-receive, update, post-receive, post-update
• push-to-checkout, pre-auto-gc, post-rewrite, sendemail-validate

Hook Uninstallation

Removes yorkie-managed Git hooks during package uninstallation.

/**
 * Uninstall Git hooks from a yorkie directory
 * @param {string} huskyDir - Path to the yorkie directory
 */
function uninstallFrom(huskyDir);

Hook Execution

The runner executes Git hook commands defined in package.json. This is automatically invoked by installed Git hooks and is not intended for direct programmatic use.

Runner Process (src/runner.js - executable script):

• Reads package.json from current working directory
• Extracts commands from gitHooks field
• Executes the appropriate command for the triggered Git hook
• Exits with proper status codes

Note: The runner is an executable Node.js script, not a module that exports functions for programmatic use.

Directory Utilities

Utilities for finding Git and package directories in complex project structures.

/**
 * Find the Git hooks directory for a given project directory
 * @param {string} dir - Project directory to search from
 * @returns {string|undefined} Path to .git/hooks directory or undefined if not found
 */
function findHooksDir(dir);

/**
 * Find parent directory containing a specific file or directory
 * @param {string} currentDir - Starting directory for search
 * @param {string} name - Name of file/directory to find
 * @returns {string|undefined} Absolute path to parent directory or undefined if not found
 */
function findParent(currentDir, name);

Hook Script Generation

Generates shell scripts for Git hooks with platform-specific Node.js environment setup.

/**
 * Generate a complete shell script for a Git hook
 * @param {string} hookName - Name of the Git hook (e.g., 'pre-commit')
 * @param {string} relativePath - Relative path from Git root to package.json
 * @param {string} runnerPath - Path to yorkie's runner.js
 * @returns {string} Complete shell script content
 */
function getHookScript(hookName, relativePath, runnerPath);

Generated Script Features:

• Cross-platform Node.js path setup (Windows, macOS, Linux)
• NVM integration for version management
• Proper error handling and exit codes
• Git parameter passing via GIT_PARAMS environment variable

Hook Detection

Utilities for detecting existing Git hook managers to handle migration scenarios.

/**
 * Check if a hook file was created by husky or yorkie
 * @param {string} filename - Path to hook file
 * @returns {boolean} true if created by husky/yorkie
 */
function huskyOrYorkie(filename);

/**
 * Check if a hook file was created by ghooks
 * @param {string} filename - Path to hook file
 * @returns {boolean} true if created by ghooks
 */
function ghooks(filename);

/**
 * Check if a hook file was created by pre-commit
 * @param {string} filename - Path to hook file
 * @returns {boolean} true if created by pre-commit
 */
function preCommit(filename);

Architecture

Yorkie follows a simple architecture designed for reliability and monorepo compatibility:

Installation Flow

1. npm install triggers bin/install.js
2. Environment checks (CI detection, skip flags)
3. src/install.js analyzes project structure
4. Prioritizes package.json next to .git directory
5. Generates hook scripts for all supported Git hooks
6. Handles migration from other hook managers (ghooks, pre-commit, husky)

Execution Flow

1. Git triggers installed hook (e.g., .git/hooks/pre-commit)
2. Hook script sets up Node.js environment and paths
3. src/runner.js reads package.json gitHooks configuration
4. Executes corresponding command with proper error handling
5. Returns appropriate exit code to Git

Key Design Principles

• Monorepo-first: Prioritizes package.json location relative to .git directory
• Migration-friendly: Automatically migrates from other hook managers
• Environment-aware: Handles CI environments and manual skip flags
• Cross-platform: Works on Windows, macOS, and Linux with proper path handling

Error Handling

Yorkie handles several error scenarios gracefully:

• Missing .git directory: Skips installation with warning message
• CI environments: Automatically skips installation unless overridden
• Nested node_modules: Prevents installation from sub-dependencies
• Existing user hooks: Preserves user-created hooks rather than overwriting
• Missing gitHooks config: Runner exits gracefully if no hooks configured
• Command failures: Proper exit codes passed to Git with descriptive error messages

Differences from Husky

Yorkie addresses specific limitations in husky for monorepo environments:

1. Package.json Discovery: Prioritizes package.json next to .git directory instead of upward search
2. Configuration Format: Uses gitHooks object instead of npm script names
3. Monorepo Compatibility: Prevents conflicts when multiple packages depend on hook managers
4. Installation Logic: Better handling of nested node_modules structures