ワークスペースの設定

ほとんどのモノレポでは、ルートディレクトリに turbo.json を宣言し、すべてのワークスペースに適用される一律の パイプラインを設定できます。場合によっては、モノレポに、タスクを異なる方法で構成する必要があるワークスペースが含まれていることがあります。これに対応するため、バージョン 1.8 以降では、Turborepo は、ルート構成を任意のワークスペース内の turbo.json で拡張できるようにします。この柔軟性により、より多様なアプリやパッケージが共存できるようになり、ワークスペースの所有者は、モノレポの他のアプリやパッケージに影響を与えることなく、特殊なタスクや構成を維持できるようになります。

仕組み

ルートの turbo.json で定義されたタスクの構成をオーバーライドするには、モノレポの任意のワークスペースに、トップレベルの extends キーを含む turbo.json ファイルを追加します。

{
  "extends": ["//"],
  "pipeline": {
    "build": {
      // custom configuration for the build task in this workspace
    },
    // new tasks only available in this workspace
    "special-task": {},
  }
}

ワークスペース内の構成は、パイプラインタスクの構成をすべてオーバーライドできます。キーを含めない場合、構成は拡張された turbo.json から継承されます。

例

例を挙げて、いくつかのユースケースを見てみましょう。

異なるフレームワーク

モノレポに複数の Next.js (新しいタブで開く) アプリと 1 つの SvelteKit (新しいタブで開く) アプリがあるとします。両方のフレームワークは、それぞれの package.json に build スクリプトを使用してビルド出力を生成します。ルートに単一の turbo.json を使用してこれらのタスクを実行するように Turborepo を構成することもできます。

{
  "pipeline": {
    "build": {
      "outputs": [".next/**", "!.next/cache/**", ".svelte-kit/**"],
    }
  }
}

.next/** と .svelte-kit/** の両方を outputs として指定する必要があることに注意してください。ただし、Next.js アプリは .svelte-kit ディレクトリを生成せず、その逆も同様です。ワークスペース構成を使用すると、代わりに apps/my-svelte-kit-app/turbo.json 内の SvelteKit ワークスペースにカスタム構成を追加できます。

{
  "extends": ["//"],
  "pipeline": {
    "build": {
      "outputs": [".svelte-kit/**"]
    }
  }
}

そして、ルート構成から構成を削除します

{
  "pipeline": {
    "build": {
-      "outputs": [".next/**", "!.next/cache/**", ".svelte-kit/**"]
+      "outputs": [".next/**", "!.next/cache/**"]
    }
  }
}

これにより、各設定が読みやすくなるだけでなく、設定が使用される場所に近くなります。

特殊なタスク

別の例として、あるワークスペースのbuildタスクがcompileタスクにdependsOnしているとします。これをdependsOn: ["compile"]として普遍的に宣言することができます。これは、ルートのturbo.jsonに空のcompileタスクのエントリが必要であることを意味します。

{
  "pipeline": {
    "build": {
      "dependsOn": ["compile"]
    },
    "compile": {}
  }
}

ワークスペース構成を使用すると、そのcompileタスクをapps/my-custom-app/turbo.jsonに移動できます。

{
  "extends": ["//"],
  "pipeline": {
    "build": {
      "dependsOn": ["compile"]
    },
    "compile": {}
  }
}

そして、ルートから削除します。

{
  "pipeline": {
+    "build": {}
-    "build": {
-      "dependsOn": ["compile"]
-    },
-    "compile": {}
  }
}

これで、my-appの所有者は、buildタスクを完全に所有できますが、ルートで定義された他のタスクを継承し続けることができます。

ワークスペース固有のタスクとの比較

一見すると、ワークスペース構成は、ルートのturbo.jsonにあるworkspace#task構文によく似ているように聞こえるかもしれません。機能は似ていますが、1つの大きな違いがあります。ルートのturbo.jsonでワークスペース固有のタスクを宣言すると、ベースラインのタスク構成が完全に上書きされます。ワークスペース構成を使用すると、タスク構成は代わりにマージされます。

複数のNext.jsアプリとSveltekitアプリを持つモノレポの例をもう一度考えてみましょう。ワークスペース固有のタスクがない場合、ルートのturbo.jsonをこのように構成する可能性があります。

{
  "pipeline": {
    "build": {
      "outputMode": "hash-only",
      "inputs": ["src/**"],
      "outputs": [".next/**", "!.next/cache/**"],
    },
    "my-sveltekit-app#build": {
      "outputMode": "hash-only", // must duplicate this
      "inputs": ["src/**"], // must duplicate this
      "outputs": [".svelte-kit/**"]
    }
  }
}

この例では、my-sveltekit-app#buildはSveltekitアプリのbuildを完全に上書きするため、outputModeとinputsも複製する必要があります。

ワークスペース構成を使用すると、outputModeとinputsは継承されるため、複製する必要はありません。outputs my-sveltekit-app構成をオーバーライドするだけで済みます。

制限事項

一般的な考え方はルートのturbo.jsonと同じですが、ワークスペース構成には、ワークスペースが混乱する状況を作成するのを防ぐことができる一連のガードレールが付属しています。これらのガードレールは、意図的なものであり、偶発的なものではないことを明確にするためにここにリストされています。

• ワークスペース構成は、パイプラインエントリとしてworkspace#task構文を使用できません。

  workspaceは、構成の場所に基づいて推論され、別のワークスペースの構成を変更することはできません。たとえば、'my-nextjs-app'のワークスペース構成では

  {
    "pipeline": {
      "my-nextjs-app#build": {
        // ❌ This is not allowed. Even though it's
        // referencing the correct workspace, "my-nextjs-app"
        // is inferred, and we don't need to specify it again.
        // This syntax also has different behavior, so we do not want to allow it.
        // (see "Comparison to Workspace-specific tasks" section)
      },
      "my-sveltekit-app#build": {
        // ❌ Changing configuration for the "my-sveltekit-app" workspace
        // from Workspace Configuration in "my-nextjs-app" is not allowed.
      },
      "build": {
        // ✅ just use the task name!
      },
    }
  }

  buildタスクは、ワークスペース固有のタスクに依存できることに注意してください。

  {
    "pipeline": {
      "build": {
        // ✅ It's still ok to have workspace#task in dependsOn!
        "dependsOn": ["some-pkg#compile"]
      },
    }
  }

• ワークスペース構成は、pipelineキーの外側にあるものをオーバーライドすることはできません。

  たとえば、globalEnvまたはglobalDependenciesをオーバーライドすることはできません。モノレポの所有者はこれを完全に制御する必要があり、この構成が真にグローバルでない場合は、そのように構成すべきではないと予想しています。

• ルートのturbo.jsonは、extendsキーを使用できません。

  ワークスペースでの循環依存関係の作成を避けるために、ルートのturbo.jsonは何も継承できません。

これらのいずれかにユースケースがある場合は、issueを提出してください (新しいタブで開きます)!

トラブルシューティング

大規模なモノレポでは、Turborepoが構成をどのように解釈しているかを理解するのが難しい場合があります。これを支援するために、ドライラン出力にresolvedTaskDefinitionを追加しました。たとえば、turbo run build --dry-runを実行すると、出力にはbuildタスクの実行前に考慮されたすべてのturbo.json構成の組み合わせが含まれます。