troubleshoot

エラーの診断と修正を行う。

診断手順

1. エラーの種類を特定

以下のコマンドを順番に実行し、どこでエラーが出ているか確認:

yarn type-check    # 型エラー
yarn lint          # ESLint エラー
yarn test          # テスト失敗
yarn build         # ビルドエラー

2. よくあるエラーと対処法

型エラー

エラー	原因	対処
Cannot find module '@geckou/shared'	shared のパスエイリアス	tsconfig.json の paths を確認
Type 'X' is not assignable to 'Y'	型の不一致	型定義を確認。as const の有無を確認
Cannot find module '@sentry/*'	パッケージ未インストール	各 lib/sentry.ts の import 行に // @ts-ignore + 直上の // eslint-disable-next-line が付いているか確認。インストール後にこの2行を削除
vite Plugin 型の不一致	node_modules の二重インストール	vitest.config.ts を tsconfig の exclude に追加

ビルドエラー

エラー	原因	対処
'use client' 関連	Server/Client の境界違反	クライアント専用 API を Server Component で使っていないか確認
server-only エラー	サーバー専用モジュール違反	import パスを確認。firebase-admin はサーバー専用
Module not found	パッケージ未インストール	yarn install を実行。import パスを確認

フォーマット（Prettier / Tailwind）

症状	原因	対処
触っていない .tsx で format:check が落ちる / コミットに className の並び替えだけの差分が混入する	packages/shared 未ビルド。prettier-plugin-tailwindcss が apps/web/tailwind.config.ts（@geckou/shared/theme を import）を解決できず、既定の Tailwind 設定にフォールバックしてクラスを別の順序に並べ替える	yarn turbo build --filter='./packages/*' を実行する。yarn format / scripts/format.sh / pre-commit フックはこれを自動で行う

MODULE_NOT_FOUND は Prettier の終了コードに影響しないため、設定を解決できなかったことはエラーにならず、黙って誤った結果が返る。ログに code: 'MODULE_NOT_FOUND' が出ていたらこれを疑う。

テスト失敗

エラー	原因	対処
Cannot find module in test	テストのモック不足	vi.mock() で外部モジュールをモック
i18n キー不一致	ja と en のキーがずれている	両方のファイルに同じキーを追加
Firebase App not initialized	テストで初期化なし	vi.mock('firebase-admin/firestore') 等でモック

3. 環境の問題

# Node.js バージョン確認
node -v  # .nvmrc の値（22.x）が期待値

# 依存関係の再インストール
rm -rf node_modules apps/*/node_modules packages/*/node_modules
yarn install

# turbo キャッシュのクリア（turbo に clean コマンドはないため直接削除する）
rm -rf .turbo apps/*/.turbo packages/*/.turbo

4. CI 固有の問題

• engines フィールドによるバージョンエラー → yarn install --ignore-engines
• GitHub Actions の Node.js 20 deprecation → FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
• yarn.lock の不整合 → ローカルで yarn install して lock ファイルをコミット