Turborepo globalEnv versus per-task env for build-time public variables

Question

Cache key stability across deployment environments

Turborepo v2 defaults to strict environment variable mode, where only variables declared in globalEnv or a task's env array participate in the task hash. Framework-prefixed variables such as NEXT_PUBLIC_* or VITE_* are inlined at build time, so their values must vary the cache key when the target environment changes. The documentation shows both globalEnv and per-task env can declare these variables, but it does not prescribe which scope is appropriate for values that differ between preview, staging, and production deployments.

Placing a variable in globalEnv forces every task in the pipeline to re-execute when that variable changes, even tasks that do not consume it. Declaring the same variable in each task's env array limits invalidation to the tasks that actually read it, but duplicates configuration and risks drift. Neither approach clearly addresses whether a shared remote cache should store separate artifacts per deployment environment or rely on a single cache key for all builds of the same commit.

Open questions

Should framework public variables live in globalEnv or per-task env when their values differ across deployment targets?
Does the remote cache key need to incorporate the deployment environment identifier, or can a single artifact be safely reused?
Is there a recommended pattern for injecting environment-specific public variables without polluting the global cache namespace?

Tasadduq Burney · Answer

Choosing a scope for deployment-specific public variables

In Turborepo v2, only variables listed in globalEnv or a task’s env array participate in the task-specific cache hash. Framework-prefixed public variables such as NEXT_PUBLIC_* or VITE_* are inlined at build time, meaning their values must vary the cache key when the target environment changes to avoid serving the wrong environment's assets.

How the two scoping modes differ

globalEnv: A variable declared here is included in every task’s cache key hash. A change to a global variable invalidates the entire pipeline, regardless of whether a specific task actually consumes that variable.
Per-task env: A variable listed in a specific task’s env array affects only that task’s cache key. Other tasks remain cached unless their own declared variables or inputs change.

Cache key reality for framework variables

Neither scoping approach automatically incorporates a deployment environment identifier (like STAGING or PROD) into the remote cache key. Framework-prefixed variables are inlined during the build process; while their specific values influence the hash, the remote cache treats the resulting artifact as a match for any environment that produces the same hash.

Practical verification steps

Inspect the task-level cache hash in the local Turborepo cache (e.g., ~/.turbocache/...) to confirm whether the variable appears in all task hashes or only declared tasks.
Toggle the variable’s value and run turbo run --dry or observe cache misses to determine if the entire pipeline or only specific tasks are re-invoked.

To finalize the recommendation, I need one missing diagnostic detail: what deployment environment identifier your pipeline currently uses (or plans to use) for differentiating preview, staging, and production builds.