RFC: Pluggable task environment providers

[yrybak-op8]

Summary

Nx's task environment is currently sourced from exactly two places: process.env and .env* files
(getTaskSpecificEnv / loadDotEnvFilesForTask in packages/nx/src/tasks-runner/task-env.js). There is no
supported extension point for other environment sources — secret managers (Doppler, Vault, 1Password, AWS
Secrets Manager, GCP Secret Manager), remote config services, or any tool that needs to inject task-scoped
variables computed at run time rather than read from a static file.

This RFC proposes a first-class, pluggable task environment provider API so plugin authors can inject
variables into a task's environment the same way Nx already lets them contribute targets, executors, and
project graph nodes — without patching Nx itself.

Problem

The only executor with a documented way to attach environment variables to a specific target is
nx:run-commands, via its envFile/env options —
and that's a property of that one executor's own schema, not something Nx provides generically. Framework
executors (@nx/vite:build, @nx/storybook:build, @nx/webpack:build/ssr-dev-server, etc.) have no
equivalent option in their schemas. For those, the only two ways to get a variable into the task are:

1. set it globally in the process running nx (shell export, CI job env, etc.), or
2. put it in a .env* file, which Nx loads workspace/project-wide when NX_LOAD_DOT_ENV_FILES is set.

Both are all-or-nothing for the whole nx invocation: there's no per-target scoping, and neither supports a
value that has to be resolved at run time from something other than a file (a secrets manager, a remote config
service, computed build metadata, etc.) without first writing it to disk or exporting it into the parent shell
before Nx even starts.

This isn't specific to JS/TS executors, either — non-JS language plugins (@nx/dotnet, @nx/gradle,
@nx/maven) go through the same core process.env + .env* mechanism. A hook in that one shared pipeline
would benefit every one of these ecosystems at once, not just JS/TS.

Motivation

We tried integrating a secrets manager as a task-scoped environment source and ran into requirements that
.env files and process.env alone can't express:

• values that are neither static files nor safe to write to disk, resolved at run time per task,
• values that must win over .env and inherited shell values,
• cache-correctness — a task's Nx hash must change when the values of its injected variables change, without
  the values themselves ever reaching a remote cache,
• an explicit way to opt out for environments that already supply the variables another way.

None of this fits .env files: the values aren't static, aren't safe to persist to disk, and the requirements
above need to be expressed somewhere richer than dotenv syntax.

Current state and why it isn't a supported extension point

Looking at packages/nx/src/tasks-runner/task-env.js, getTaskSpecificEnv does exactly this, in order:

1. reset to a clean process.env (unloadDotEnvFiles),
2. optionally merge .env* files for the task (NX_LOAD_DOT_ENV_FILES === 'true'),
3. return the result, which getEnvVariablesForTask later merges under Nx's own internal env vars.

There is no hook between steps 2 and 3, no plugin lifecycle event fires with the resolved task and project
graph before the child process spawns, and no TaskEnvironmentProvider type is exported.

To get this working at all, we ended up carrying a local patch on top of Nx that:

• adds an env var naming a module to load, resolved once and cached,
• calls that module's default export as (task, graph, env) => env | void inside getTaskSpecificEnv, after
  dotenv loading, before Nx's own overrides,
• throws if the provider function returns a Promise (synchronous only, since this sits on the hot path of
  hash computation, not just process spawn).

This works, but every Nx upgrade touching tasks-runner/task-env.js is a patch to re-review, and anyone else
who wants the same capability has to discover and re-derive an equivalent patch independently. A patched
dependency is also invisible to anyone auditing the repo's actual dependency tree.

Why the existing preTasksExecution hook isn't enough

Nx plugins already get an async preTasksExecution(options, context) lifecycle hook, and we do use it for the
part of this that fits: setting a handful of variables once, globally, before the run starts, by mutating
process.env directly. It falls short of per-task injection for a few reasons:

• it runs once per nx invocation, not once per task, and has no access to the individual Task or where
  in the project graph it sits — so it cannot express "these variables for target A, those for target B" within
  the same nx run-many,
• mutating process.env inside it is global for the whole process, which any task can read — it can't
  scope a value to only the tasks that declared they need it,
• it runs before task hashing, but has no return-value contract for feeding computed values back into the
  per-task hash the way inputs: [{ "env": "..." }] does — anything it sets ends up as ambient environment, not
  as a tracked, cache-affecting input tied to a specific task,
• it's async, which is fine for a one-time setup step, but getTaskSpecificEnv (where per-task env is
  actually assembled) is synchronous and runs on the hot path of hash computation, so a hook meant to plug into
  it needs the same synchronous contract our patch enforces.

In short, preTasksExecution covers "inject some global config once at the start," which is a real and useful
case, but not "resolve different values per task, tied into that task's own hash." That second case is what
this RFC is about, and it needs a hook that sees the Task itself, not just the workspace root.

Proposed API

Expose this as a documented Nx plugin lifecycle hook, analogous to preTasksExecution/postTasksExecution
in nx/src/project-graph/plugins/public-api, rather than an ad hoc env var pointing at a module path.

// nx/src/project-graph/plugins/public-api.ts
export type TaskEnvironmentProvider<TOptions = unknown> = (
  task: Task,
  graph: ProjectGraph,
  context: { workspaceRoot: string; options: TOptions }
) => NodeJS.ProcessEnv | void

export interface NxPluginV2 {
  // ...existing hooks
  provideTaskEnvironment?: TaskEnvironmentProvider
}

Deliberately, the hook does not receive the environment assembled so far (.env values, other plugins'
contributions). A provider only returns the variables it wants to add — Nx merges those on top afterwards. If
the hook received the running environment, one plugin's provider could read values injected by .env or by
another provider for an unrelated purpose (e.g. a secrets-manager plugin reading a variable some other plugin
resolved from its own vault), which defeats the point of scoping a value to only the tasks that declared they
need it. Keeping providers write-only relative to each other is what makes composing multiple
provideTaskEnvironment plugins on the same task safe.

Plugins would register it the same way they already register createNodes/createDependencies in
nx.json#plugins. getTaskSpecificEnv would fold every registered provideTaskEnvironment hook's return value
into the pipeline after .env loading (multiple plugins could compose, each contributing disjoint variables).
The hook would stay synchronous, for the same hot-path reason our patch enforces it today.

One smaller, related gap fell out of trying to build this against real infrastructure: cache-affecting env
inputs only version known variable names (inputs: [{ "env": "SOME_VAR" }]). A provider that injects a
dynamic, allow-list-defined set of variables needs a way to say "hash whatever this plugin injected" without
enumerating every name in project.json up front.

What this would unlock

With provideTaskEnvironment in place, a community or first-party @nx/doppler plugin (or the equivalent for
Vault, 1Password, etc.) could exist as a normal, installable Nx plugin rather than something every workspace
re-implements against a patched dependency:

• it would read the project's doppler.yaml (Doppler's own convention for mapping a directory to a
  project/config) to know which Doppler project backs which part of the workspace,
• target configurations would select which Doppler config to pull from (e.g. a production configuration on
  a target maps to that project's production config) — reusing a concept Nx already has, instead of introducing
  parallel environment-selection syntax,
• a doppler:run-command executor would exist as a drop-in alternative to nx:run-commands for targets that
  are genuinely "run one shell command," injecting Doppler secrets the same way nx:run-commands' own
  envFile injects a dotenv file's contents,
• provideTaskEnvironment would be what makes that same injection reach targets that use a framework executor
  instead (@nx/vite:build, @nx/storybook:build, etc.) — those have no env/envFile option of their own
  and can't switch to doppler:run-command, since that would mean giving up the executor itself,
• none of this would require writing secrets to a .env file on disk or exporting them into the OS-level shell
  environment before Nx starts — values would be resolved and injected per task, scoped to exactly the process
  that needs them.

That's the shape of the plugin this RFC is trying to make possible; it isn't proposing Nx ship Doppler support
itself, only the hook that lets a plugin like this be built without patching Nx.

Alternatives considered

• Shell wrapper around the whole nx invocation (e.g. secrets-cli run -- nx run app:build): works for a
  single top-level invocation, but can't scope differently per target within one nx run-many, and doesn't
  participate in cache-hashing since the wrapping happens entirely outside Nx's task graph.
• Executor-level wrapping (a custom executor per project that resolves secrets before delegating to the
  real executor): loses the target's original executor/schema/options/cache metadata, and has to be re-applied
  to every target that needs secrets instead of being declared once.
• Keep it as an unsupported env-var hook (status quo, via a patched dependency): works, but is invisible to
  nx migrate, requires re-patching on every relevant Nx upgrade, and isn't discoverable by anyone building a
  similar integration.