website-enchun-mgr/.opencode/skills/turborepo/references/environment/gotchas.md

Environment Variable Gotchas

Common mistakes and how to fix them.

.env Files Must Be in inputs

Turbo does NOT read .env files. Your framework (Next.js, Vite, etc.) or dotenv loads them. But Turbo needs to know when they change.

Wrong:

{
  "tasks": {
    "build": {
      "env": ["DATABASE_URL"]
    }
  }
}

Right:

{
  "tasks": {
    "build": {
      "env": ["DATABASE_URL"],
      "inputs": ["$TURBO_DEFAULT$", ".env", ".env.local", ".env.production"]
    }
  }
}

Strict Mode Filters CI Variables

In strict mode, CI provider variables (GITHUB_TOKEN, GITLAB_CI, etc.) are filtered unless explicitly listed.

Symptom: Task fails with "authentication required" or "permission denied" in CI.

Solution:

{
  "globalPassThroughEnv": ["GITHUB_TOKEN", "GITLAB_CI", "CI"]
}

passThroughEnv Doesn't Affect Hash

Variables in passThroughEnv are available at runtime but changes WON'T trigger rebuilds.

Dangerous example:

{
  "tasks": {
    "build": {
      "passThroughEnv": ["API_URL"]
    }
  }
}

If API_URL changes from staging to production, Turbo may serve a cached build pointing to the wrong API.

Use passThroughEnv only for:

• Auth tokens that don't affect output (SENTRY_AUTH_TOKEN)
• CI metadata (GITHUB_RUN_ID)
• Variables consumed after build (deploy credentials)

Runtime-Created Variables Are Invisible

Turbo captures env vars at startup. Variables created during execution aren't seen.

Won't work:

# In package.json scripts
"build": "export API_URL=$COMPUTED_VALUE && next build"

Solution: Set vars before invoking turbo:

API_URL=$COMPUTED_VALUE turbo run build

Different .env Files for Different Environments

If you use .env.development and .env.production, both should be in inputs.

{
  "tasks": {
    "build": {
      "inputs": [
        "$TURBO_DEFAULT$",
        ".env",
        ".env.local",
        ".env.development",
        ".env.development.local",
        ".env.production",
        ".env.production.local"
      ]
    }
  }
}

Complete Next.js Example

{
  "$schema": "https://turborepo.dev/schema.v2.json",
  "globalEnv": ["CI", "NODE_ENV", "VERCEL"],
  "globalPassThroughEnv": ["GITHUB_TOKEN", "VERCEL_URL"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "env": [
        "DATABASE_URL",
        "NEXT_PUBLIC_*",
        "!NEXT_PUBLIC_ANALYTICS_ID"
      ],
      "passThroughEnv": ["SENTRY_AUTH_TOKEN"],
      "inputs": [
        "$TURBO_DEFAULT$",
        ".env",
        ".env.local",
        ".env.production",
        ".env.production.local"
      ],
      "outputs": [".next/**", "!.next/cache/**"]
    }
  }
}

This config:

• Hashes DATABASEURL and NEXT_PUBLIC* vars (except analytics)
• Passes through SENTRY_AUTH_TOKEN without hashing
• Includes all .env file variants in the hash
• Makes CI tokens available globally