環境変数入力

環境変数はソースコードに捕捉されないため、マシン間で簡単に共有することはできません。開発者とCI間で異なるマシン間で一貫した環境設定を確保することは困難な作業です。Turborepoは、アプリケーションが依存する環境変数を表現するためのツールを提供します。

設定

Turborepoを使用すると、グローバルレベルとpipelineレベルの両方で、ハッシュキーに考慮する必要がある環境変数を直接列挙できます。

{
  "$schema": "https://turbo.dokyumento.jp/schema.json",
  "globalEnv": ["API_BASE_URL"],
  "pipeline": {
    "test": {
      "env": ["MOCHA_REPORTER"]
    },
    //...
  }
}

この例では、テスト環境、ステージング環境、本番環境で異なるAPI_BASE_URLを持つアプリケーションを想定できます。この設定により、API_BASE_URLの値がハッシュに考慮され、値が異なる場合は、タスクがキャッシュから復元されません。

さらに、testタスクは、MOCHA_REPORTERの値に基づいて異なるキャッシング動作が必要となる場合があります。これは、CIがローカル開発とは異なるサービスと統合できるようにするために使用できます。

globalEnv

globalEnvキーに含まれる環境変数は、すべてのタスクのハッシュに影響します。

pipeline.<task>.env

pipeline.<task>.envに含まれる環境変数は、そのタスクのみのハッシュに影響します。

ワイルドカード

turbo.jsonで環境変数を受け入れる場所はすべてワイルドカードを受け入れます。これには、タスクレベルのenvとグローバルレベルのglobalEnvが含まれます。これにより、包含と除外の両方で、環境変数のパターン名(正規表現など)を簡単に指定できます。

{
  "$schema": "https://turbo.dokyumento.jp/schema.json",
  "pipeline": {
    "build": {
      "env": ["NEXT_PUBLIC_*", "!NEXT_PUBLIC_GIT_*"]
    }
  }
}

除外パターンは、包含によって一致する変数のセットにのみ適用されます。

構文

• *はパターン内の任意の場所に配置すると、0個以上の文字に一致します。
• 先頭に!がある場合、パターン全体が否定されます。
• 先頭以外の位置に!がある場合は、リテラルの!となります。
• 特別な意味を持つ文字（先頭の!と*）は、前に\を付けることでエスケープし、リテラル値を取得できます。

例

• "*"：すべての環境変数に一致します。
• "!*"：すべての環境変数を除外します。
• "FOO*"：FOO、FOOD、FOO_FIGHTERSなどに一致します。
• "FOO\*"：これはJSONで指定されているため、"FOO*"として解決され、FOO、FOOD、FOO_FIGHTERSなどに一致します。
• "FOO\\*"：FOO*という名前の環境変数1つに一致します。
• "!FOO*"：FOOで始まるすべての環境変数を除外します。
• "\!FOO"：これはJSONで指定されているため、"!FOO"として解決され、!FOOという名前の環境変数1つを一致するセットから除外します。
• "\\!FOO"：!FOOという名前の環境変数1つに一致します。
• "FOO!"：FOO!という名前の環境変数1つに一致します。

緩い環境モードと厳格な環境モード

Turborepoは、タスクでの環境変数の処理に、looseモードとstrictモードの2つの異なるモードを提供します。このモードは、実行時に各タスクで使用可能になる環境変数を制御します。

緩いモード

デフォルトの動作である緩いモードでは、環境変数はフィルタリングされません。そのため、マシンのすべての環境変数がすべてのタスクで使用可能になります。これにより、タスクが暗黙的に指定されていない環境変数にアクセスするリスクを受け入れる一方で、最高の互換性が確保されます。ユーザーは環境変数の値を変えてタスクを実行できますが、turbo.jsonに環境変数が設定されていないため、誤ってFULL TURBOが表示される可能性があります。

厳格なモード

turbo --env-mode=strictで有効にできる厳格なモードでは、環境変数がフィルタリングされます。

重要なシステム環境変数とturbo.json内で設定された環境変数のみが、タスクで使用可能になります。

環境変数をキャッシュキーの一部に含める場合は、ハッシュされた環境変数を使用してください。

環境変数をキャッシュキーの一部に**含めない**場合は、ハッシュされていない環境変数を使用してください。

システム環境変数

Turborepoは、厳格モードでも、次の環境変数をすべてのタスクに渡します。

• PATH
• SHELL
• SYSTEMROOT

ハッシュされた環境変数

globalEnvとenvで定義されたハッシュされた環境変数は、タスクで使用可能になり、ハッシュされたキャッシュキーに含まれます。

NODE_ENVなど、値によってタスクの出力が変わる可能性のある環境変数は、globalEnvまたはenvに含める必要があります。

ハッシュされていない環境変数

globalPassThroughEnvとpassThroughEnvで定義されたハッシュされていない環境変数は、タスクで使用可能になりますが、ハッシュされたキャッシュキーには**含まれません**。

NPM_TOKENなどのユーザーごとに変わるアクセストークンは、タスクの出力が同じになるため、globalPassThroughEnvとpassThroughEnvで定義する必要があります。

推論モード

Turborepoは、設定から`strict`動作の必要性を推測することで、厳格モードの段階的な導入を可能にします。

• "globalPassThroughEnv": []。すべてのタスクで厳格モードが有効になります。環境変数はホワイトリストに登録されません。
• "passThroughEnv": []。特定のタスクで厳格モードが有効になります。環境変数はホワイトリストに登録されません。

.envファイル

フレームワークでは一般的にdotenv (新しいタブで開きます)を使用して、タスクの環境変数を自動的に読み込みます。これにより、Turborepoがデフォルトでタスクの環境を理解することが難しくなります。

• .envファイルは、環境変数を環境ではなく *ファイル* に格納します。
• このファイルからの環境変数は、Turborepoがタスクの実行を開始した *後* に読み込まれます。
• このファイルは多くの場合.gitignoreに指定されているため、Turborepoはデフォルトでタスクハッシュに含めません。

ファイル入力のみを使用してこれを正しく設定することの複雑さを考慮して、Turborepoは.envファイルパターンをglobalDotEnvおよびdotEnvフィールドを使用して明示的にサポートしています。turbo.json内。Turborepoに適切な.envファイル群を考慮させるには、turbo.json内で指定します。以下は、Next.jsアプリケーションの正しいdotEnv設定です。

{
  "$schema": "https://turbo.dokyumento.jp/schema.json",
  "globalDotEnv": [".env"],
  "pipeline": {
    "build": {
      "dotEnv": [".env.production.local", ".env.local", ".env.production", ".env"]
    },
    "dev": {
      "dotEnv": [".env.development.local", ".env.local", ".env.development", ".env"]
    },
    "test": {
      "dotEnv": [".env.test.local", ".env.test", ".env"]
    }
  }
}

これらのフィールドは、globalDotEnvの場合はルートを基準とした、dotEnvの場合はワークスペースを基準とした、Unix形式（/区切り）のパスからなる *順序付き* リストです。グロブや絶対パスはサポートされていません。

フレームワークの推論

デフォルトでは、TurborepoはTurborepo内のワークスペースのフレームワークを検出し、すべてのデフォルトの環境変数がタスクハッシュに正しく考慮されるようにします。

Turborepoがフレームワークを正常に検出した場合、turbo.jsonのパイプライン設定内で、特定のフレームワーク固有の環境変数を手動で指定する必要はありません。Turborepoがタスクのenvキーに含めるサポートされているフレームワークと環境ワイルドカードを以下に示します。

Turborepoがワークスペースのフレームワークを正常に検出したかどうかを確認するには、

• 実行サマリー（--summarize経由）を確認します。
• ドライランからの出力（--dry経由）を確認します。

フレームワークの推論の除外

Turborepoがフレームワークの推論から自動的に含めるワイルドカードは、CIプラットフォームによって環境に挿入される環境変数にも一致することがあります。これらの変数には、実行IDやGit SHAなど、含まれている場合にキャッシュヒットが絶対に得られないものが含まれる場合があります。

その結果、Turborepoは変数をハッシュから除外する2つの方法を提供します。

1. TURBO_CI_VENDOR_ENV_KEYを除外プレフィックス付きで設定します。Turborepoを使用していることを検出した場合、これは理想的にはCI環境によって処理されます。たとえば、VercelでビルドしているNext.jsアプリケーションの場合、VercelはTURBO_CI_VENDOR_ENV_KEY=NEXT_PUBLIC_VERCEL_を設定して、キャッシングの問題を引き起こす変数が含まれないようにします。この変数は、推論されたフレームワーク変数に対してのみ処理されます。

2. 適切なtask定義のenvで"env": ["!NEXT_PUBLIC_UNNEEDED_*"]を使用して、除外を手動で指定します。これにより、ハッシュの考慮から環境変数の除外を非常に細かく制御できます。

フレームワークの推論はワークスペースごと

環境変数は、そのフレームワークが使用されているワークスペースのタスクのキャッシュキーにのみ含まれます。つまり、Next.jsアプリで推論された環境変数は、Next.jsアプリとして検出されたワークスペースのキャッシュキーにのみ含まれます。モノレポ内の他のワークスペースのタスクには含まれません。

たとえば、2つの別々のワークスペース（next-appとutils）のビルド動作を指定するこのturbo.jsonは、next-appに対してのみNEXT_PUBLIC_*を含みます。

{
  "$schema": "https://turbo.dokyumento.jp/schema.json",
  "pipeline": {
    "next-app#build": {
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "utils#build": {
      "outputs": ["dist/**"],
    },
  }
}

eslint-config-turbo

ビルドに忍び寄る見えない環境変数の依存関係の検出を支援し、Turborepoキャッシュが環境間で正しく共有されるようにするために、eslint-config-turbo (新しいタブで開きます)パッケージを使用します。このESLint設定は、Turborepoがturbo.json内で未指定として検出した環境変数の使用に関するオーサリング時のフィードバックを提供します。

開始するには、eslintrc (新しいタブで開きます)ファイルでeslint-config-turboから拡張します。

{
  // Automatically flag env vars missing from turbo.json
  "extends": ["turbo"]
}

ルールをより詳細に制御するには、eslint-plugin-turbo (新しいタブで開きます) プラグインを最初にプラグインに追加し、目的のルールを構成することで、直接インストールして構成できます。

{
  "plugins": ["turbo"],
  "rules": {
    // Automatically flag env vars missing from turbo.json
    "turbo/no-undeclared-env-vars": "error"
  }
}

このプラグインは、turbo.jsonに宣言されていない、フレームワーク関連以外の環境変数をコードで使用している場合に警告します。

{
  "scripts": {
    "build": "source .env && next build"
  }
}

export NEXT_PUBLIC_GA_ID=UA-00000000-0

{
  "$schema": "https://turborepo.org/schema.json",
  "pipeline": {
    "build": {
      "env": ["NEXT_PUBLIC_GA_ID"],
      "outputs": [".next/**", "!.next/cache/**"],
    },
  }
}