troubleshoot
ビルドエラー・型エラーの診断と修正
Instal·la
npx skillscat add geckou/project-starter/troubleshoot Instal·la des del registre de SkillsCat.
SKILL.md
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/*/.turbo4. CI 固有の問題
enginesフィールドによるバージョンエラー →yarn install --ignore-engines- GitHub Actions の Node.js 20 deprecation →
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true yarn.lockの不整合 → ローカルでyarn installして lock ファイルをコミット
Categories
Instal·la
npx skillscat add geckou/project-starter/troubleshoot Instal·la des del registre de SkillsCat.
Estrelles del repositori
El nombre d’estrelles correspon al repositori (geckou/project-starter), no a aquest skill concret.
.claude/skills/troubleshoot