リポジトリ
ドキュメント
トラブルシューティング

トラブルシューティングの実行

ほとんどのツールと同様に、Turborepoが期待通りに動作しない理由を理解するのは難しい場合があります。このページでは、turbo CLIを使用する場合のデバッグツールと、発生する可能性のある一般的な問題について説明します。

詳細ログを有効にする

開発者にとって最高のデバッグツールはログです。--verbosity フラグを使用してログレベルを上げることができます。ソースからのビルドと組み合わせることで、内部で何が起こっているかを把握するための強力で柔軟な方法となります。

実行サマリーを確認する

--summarize フラグは、turbo runに関するメタデータをJSONファイルとして.turbo/runsに生成して保存します。これを使用して、後続の実行を比較したり、キャッシュされたアーティファクトの内容やタスクのハッシュへの入力を検査したりできます。

設定を確認する

タスク設定

Turborepoは最小限の設定で開始できます。これはTurborepoの利点の一つです！しかし、設定を省略すると、Turborepoは内部的にスマートなデフォルト設定に戻ります。さらに、モノレポでワークスペース設定を使用する場合、Turborepoがturbo.jsonをどのように解釈したかを理解するのが難しい場合があります。--dryまたは--dry=jsonを使用して、任意のタスクの「解決済み」タスク設定を取得できます。例：

turbo run build --dry=json

出力でresolvedTaskConfigurationキーを探します。

ユーザー設定

リポジトリをVercelにリンクすると、Turborepoは2つの場所に設定を保存します。

  • Vercelチームの情報は.turbo/config.jsonに保存されています。このファイルを確認して、他に何が含まれているかを確認できます！
  • 認証トークンは~/Library/Application\ Support/turborepo/config.jsonに保存されています。

キャッシュの検査

turborepoがoutputsが設定されたタスクを実行すると、そのタスクのログと共に、それらの出力がnode_modules/.cache/turbo/にキャッシュされます。tarで圧縮されますが、解凍して内容を確認できます。

ソースからのビルド

JavaScriptコードベースの利点の1つは、node_modules/を開いて、実行中のコードをインラインで編集できることです。これはturboでは不可能です。実行可能なコードはコンパイル済みバイナリであり、インラインで編集できないためです。しかし、コードベースはオープンソースであるため、いつでもソースコードを取得し、修正してローカルでビルドできます。このドキュメントの大部分は貢献ガイド (新しいタブで開きます)で提供されていますが、貢献を予定していなくても、これらの手順を使用できます。

  1. vercel/turboからgitリポジトリをクローンします (新しいタブで開きます)
  2. cd cli
  3. 変更を加える（例：ログを追加する）
  4. makeを実行する
  5. プロジェクトから、グローバルなturboやプロジェクトにインストールされているturboのバージョンではなく、/:path/:to/:turbo/target/debug/turboを使用します。

よくある問題

ネストされたワークスペース

Turborepoはネストされたワークスペースをサポートしていません。そのため、ワークスペースに別のワークスペースが含まれている場合、予期しない動作が発生する可能性があります。この問題を回避するために、ワークスペース構造をフラットにすることをお勧めします。

ルート依存関係

モノレポで定義され、モノレポ内の他のいくつかのパッケージ（標準のESLint設定など）で使用されるパッケージがある場合、モノレポのルートにあるpackage.jsonにそれをルート依存関係として宣言することで、それをリストしたくなるかもしれません。これにより、各パッケージのpackage.jsonに宣言する必要なく、モノレポ全体で依存関係を使用できます。しかし、これは予期しないキャッシュヒットにつながる可能性があります。なぜなら、Turboはルート内部依存関係、つまりモノレポのpackage.json（ルート）で宣言され、モノレポ（内部）で実装されている依存関係を、そのキャッシュシグネチャに**含めない**ためです。したがって、ルート内部依存関係が変更された場合、他のパッケージは再構築されません。

これを解決するには、常にパッケージの内部依存関係をそのpackage.jsonに明示的に追加します。その方法についてはこちらで説明しています。

.turboディレクトリ

Turboのコアコンセプトの1つは、宣言された入力が変更されると、そのタスクのキャッシュされた出力が無効になることです。タスクを実行する際に、Turborepoは次のディレクトリを作成します。

  • リポジトリのルートにある.turbo
  • プロジェクトがモノレポの場合、各ワークスペースに.turboディレクトリ（例：apps/my-app/.turbo/）
  • node_modules/.cache内のturboディレクトリ

最初の2つのディレクトリはデフォルトではgitで無視されないため、何も変更していないのに同じタスクを2回実行してキャッシュが見つからないという問題が発生する可能性があります。生成された.turboディレクトリがタスクの入力として含まれ、キャッシュが無効になるためです。この問題を回避するには、.turboを.gitignoreファイルに追加します。あるいは、inputs設定を制限して、.turboがキャッシュ入力に含まれないようにすることもできます。

よくある質問

キャッシュヒットが見られない

一般的に、turbo runを連続して2回実行すると、2回目の実行でキャッシュヒットが得られると期待する必要があります。これが発生しない場合は、--summarizeフラグを使用して両方のビルドを再実行し、生成された実行サマリーを互いに比較します。ほとんどの場合、比較によって2回目の実行でキャッシュヒットが得られなかった理由を示すことができます。

また、次の点も確認してください。

キャッシュヒットが発生するが、ビルドが壊れている

ビルドが誤った環境変数をキャッシュしている

モノレポに関するよくある質問

依存関係が正しくビルドされない

  • アプリケーションをビルドする前に、依存関係を適切にバンドルおよびトランスパイルしていますか？

    例えば、tsc、tsup、esbuild、babel、swcといったライブラリは、新しいJavaScriptの機能を「純粋な」JavaScriptに変換します。

    Next.jsを使用している場合、transpilePackagesを使用している可能性があります。next.config.jsの中に依存関係の名前を追加してください（例（新しいタブで開きます））。

  • 依存関係のpackage.json内で、filesを正しいファイルを示すように設定しましたか？

型が見つからない

  • 依存関係のpackage.json内で、typesまたはtypingを.d.tsファイルを指すように指定しましたか？

  • tsconfig.jsonのpathsを変更またはカスタム設定しましたか？

    • アプリケーションに適切なフォルダ構造になっていますか？
    • メタフレームワーク、バンドラー、またはトランスパイルツールに対して適切に設定されていますか？