プッシュできない！HuskyとBiomeエラーを5分で解決する方法

October 28, 2025October 30, 2025

コミットしようとしたら「コミット成功 ✅」となったのに、いざプッシュしようとすると「Huskyが動いた 🐶」「Biomeがエラー検出 ❌」「プッシュが止まった 🛑」という経験はありませんか？

この記事では、HuskyとBiomeによるプッシュエラーを5分で解決する方法を、実際のエラー例を交えながら分かりやすく解説します。緊急対応から根本的な解決策まで、段階的にご紹介します。

プッシュが止まった時の症状と原因

Huskyが動作する仕組み

HuskyはGitフックを簡単に管理できるツールです。プッシュやコミットなどの特定のGit操作時に、自動的にスクリプトを実行します。

一般的な流れは以下の通りです：

git commit → ローカルに変更を保存（成功）
git push → プッシュ前にHuskyが起動
Huskyがpre-pushフック実行 → Biomeなどのチェックツールを起動
エラーがあればプッシュ中断 → GitHubへのアップロードが停止

つまり、ローカルコミットは成功しているが、リモートへの反映が止まっている状態です。

Biomeによるコード品質チェック

BiomeはRust製の高速なLinter + Formatterツールです。ESLintとPrettierの機能を1つのツールで提供し、コードの品質を自動チェックします。

Biomeがチェックする主な項目：

構文エラー：間違ったJavaScript/TypeScriptコード
スタイル違反：コードフォーマット、命名規則など
潜在的バグ：未使用変数、型エラーなど
アクセシビリティ問題：HTML要素の不適切な使用

よくあるエラーパターン

実際によく遭遇するエラーメッセージの例：

husky - pre-push hook failed (add --no-verify to bypass)

✖ Found 1 error in 1 file:
  
  src/components/HubSpotForm.tsx:15:25
  × Avoid using fixed IDs in HTML elements
  
  > 15 | 
       |         ^^^^^^^^^^^^^^^^^^^^^^
    16 |   {/* HubSpot form content */}
    17 | 
  
  ℹ Fixed IDs can cause conflicts in dynamic applications

このエラーは「固定ID（hubspot-form-container）を使うのは好ましくない」というBiomeのルール違反を示しています。

緊急対応：エラーを即座に解決する

1. 一時的にチェックをスキップする方法

今すぐプッシュしたい場合は、以下のコマンドでHuskyのチェックを一時的にスキップできます：

# Huskyのチェックをスキップしてプッシュ
git push --no-verify

# または、コミット時にもスキップする場合
git commit -m "fix: urgent bug fix" --no-verify
git push --no-verify

⚠️ 注意：これは緊急時のみの対応です。コードの品質チェックを回避するため、後で必ず修正しましょう。

2. 固定IDエラーの修正方法

固定IDエラーの根本的な解決方法です：

// ❌ 修正前：固定IDを使用
function HubSpotForm() {
  return (
    
      {/* HubSpot form content */}
    
  );
}

// ✅ 修正後：動的IDまたはクラス名を使用
import { useId } from 'react';

function HubSpotForm() {
  const formId = useId(); // Reactの動的ID生成
  
  return (
    
      {/* HubSpot form content */}
    
  );
}

// または、クラス名を使用する方法
function HubSpotForm() {
  return (
    
      {/* HubSpot form content */}
    
  );
}

3. 特定のルールを無効化する方法

どうしても固定IDが必要な場合は、そのファイルでのみルールを無効化できます：

function HubSpotForm() {
  return (
    // biome-ignore lint/a11y/useValidId: HubSpot requires this specific ID
    
      {/* HubSpot form content */}
    
  );
}

4. 安全なプッシュの手順

エラーを修正した後の確実なプッシュ手順：

# 1. 修正したファイルをステージング
git add src/components/HubSpotForm.tsx

# 2. ローカルでBiomeチェックを実行
npx @biomejs/biome check --write ./src

# 3. 問題がなければコミット
git commit -m "fix: resolve fixed ID error in HubSpot form"

# 4. プッシュ実行（Huskyが自動でチェック）
git push

HuskyとBiomeの基本理解

それぞれのツールの役割

ツール	役割	実行タイミング
Husky	Gitフックの管理	commit、push、merge時
Biome	コード品質チェック	Huskyから呼び出される
lint-staged	変更ファイルのみ処理	pre-commitフック時

プリコミットフックとは

プリコミットフック（pre-commit hook）は、コミット実行前に自動的に実行されるスクリプトです。主な目的：

品質保証：問題のあるコードの混入を防ぐ
自動化：手動チェックの忘れを防止
統一性：チーム全体でコーディング規約を強制
効率化：レビュー時間の短縮

チーム開発での重要性

HuskyとBiomeの組み合わせがチーム開発で重要な理由：

コード品質の均一化：メンバー間のスキル差を補完
レビュー効率化：機械的チェックは自動化、本質的な議論に集中
バグの早期発見：マージ前にエラーを検出
設定の共有：package.jsonで設定を統一

実践的な設定とカスタマイズ

Huskyの設定方法

Husky v9（最新版）の設定手順：

# 1. Huskyをインストール
npm install --save-dev husky

# 2. Huskyを初期化
npx husky init

# 3. pre-commitフックを設定
echo "npx lint-staged" > .husky/pre-commit

# 4. pre-pushフックを設定（オプション）
echo "npm test" > .husky/pre-push

package.jsonに以下を追加：

{
  "scripts": {
    "prepare": "husky install"
  },
  "devDependencies": {
    "husky": "^9.0.0",
    "lint-staged": "^15.0.0"
  }
}

Biomeのルール設定

biome.jsonでのカスタマイズ例：

{
  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "style": {
        "useNamingConvention": "error"
      },
      "a11y": {
        "useValidId": "warn"  // 固定IDエラーを警告レベルに
      },
      "nursery": {
        "noConsole": "error"  // console.logを禁止
      }
    }
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingComma": "es5"
    }
  }
}

プロジェクトに応じた調整

lint-stagedでの効率的な設定：

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "npx @biomejs/biome check --write --no-errors-on-unmatched",
      "git add"
    ],
    "*.{json,md}": [
      "npx @biomejs/biome format --write",
      "git add"
    ]
  }
}

この設定により、変更されたファイルのみにBiomeを適用し、処理時間を短縮できます。

今後エラーを防ぐベストプラクティス

開発時の注意点

エラーを未然に防ぐための開発習慣：

VSCode拡張機能の活用：Biome拡張機能でリアルタイムチェック
コミット前の事前チェック：npm run checkで手動確認
小さなコミット：変更範囲を限定してエラー特定を容易に
ルールの理解：よく遭遇するエラーパターンを覚える

効率的なワークフロー

推奨する開発フロー：

# 1. 機能開発
# ... コーディング作業

# 2. 開発完了時のセルフチェック
npm run lint     # Biomeのlintチェック
npm run format   # フォーマット実行
npm run test     # テスト実行

# 3. 問題なければコミット
git add .
git commit -m "feat: add new feature"

# 4. プッシュ（Huskyが自動チェック）
git push

チーム運用のコツ

チーム全体でスムーズに運用するためのポイント：

共通設定の管理：biome.jsonをGit管理下に置く
新メンバーのオンボーディング：セットアップ手順を文書化
ルール調整の合意形成：厳しすぎるルールは段階的に導入
トラブルシューティング共有：よくあるエラーの解決法を共有

パフォーマンス最適化

Husky + Biomeの実行速度を向上させる設定：

{
  "files": {
    "ignore": [
      "**/node_modules/**",
      "**/dist/**",
      "**/build/**",
      "**/.next/**",
      "**/coverage/**"
    ]
  },
  "linter": {
    "rules": {
      "recommended": true
    }
  }
}