Feature: Nx-style dotenv resolution per task (target/config precedence)

[gabrielbryk]

Summary

Moon currently supports a single static envFile per task. Nx provides built-in dotenv resolution that automatically loads env files based on target and configuration with an ordered precedence (target+config, config-only, target-only, general, plus .local variants, skipping .local in CI). See Nx docs: https://nx.dev/docs/guides/tips-n-tricks/define-environment-variables.

Problem

• Migrating from Nx requires recreating Nx's env loading semantics manually. There is no built-in way to stack multiple env files (base, base.local, target, target.local, target+config, etc.) and to honor CI skipping of .local.
• envFile is single-file and static; no target/config-aware resolution.

Desired behavior / parity with Nx

• Built-in dotenv resolution that mirrors Nx's precedence for target/config: load env files for target+config (and .local), then config-only (and .local), then target-only (and .local), then general (.env/.env.local), ignoring missing files and skipping .local in CI by default.
• Support both project-root and workspace-root env files (as Nx does) with the same precedence rules.
• Allow optional runtime override for target/config (env vars or CLI) without duplicating tasks.

Possible implementation avenues

• Extend task options to support multiple env files via tokens (e.g., @target, @config) and a loadLocal toggle (default skip in CI).
• Or a workspace-level dotenv resolution setting applied automatically to all tasks with opt-out.
• Alternatively, extend plugin/task lifecycle hooks so a WASM plugin can intercept task execution to apply Nx-like dotenv resolution.

Motivation

• Feature parity with Nx for dotenv handling removes migration friction, reduces boilerplate, and clarifies env loading semantics for Moon users coming from Nx.

[milesj]

@gabrielbryk Just to note, you can define a list for envFile. It's not just a single file.

[gabrielbryk]

Thanks! I’m aware envFile accepts a list. The request is about not having to declare env files explicitly per task and matching Nx’s implicit target/config precedence.

In Nx I can commit shared defaults (e.g., root .env with DB_URL) and let per-target overrides Just Work (e.g., an app-level .env.serve or .env.build), with .local skipped in CI by default. It finds the right combination based on the target/config without me wiring paths into every task.

That implicit resolution + precedence (target+config, config, target, general; project root and workspace root; .local overrides) is the parity we’re asking for, so devs don’t need to hand-maintain envFile lists on every task.

[gabrielbryk]

@milesj I’ve never contributed here before, but I’d like to with this feature if this is something that is desired (similar issues seem to already exist #2151 #1978 . Before digging into the code, I want to validate the direction and see how to cover adjacent asks.

Proposal options

1. Core, opt-in: Implement Nx-like implicit resolution directly in TaskExpander::expand_env (or similar), building the ordered list: target+config (.local skipped in CI) → config (.local) → target (.local) → general (.env/.env.local) from both project and workspace roots. Honor runtime target/config overrides and keep these files in task inputs for hashing. To help [feature] defered dotenv evaluation #2151, resolve env at run time or just-in-time so newly created dotenv files are seen.

2. PDK hook: Add a task-env hook (e.g., resolve_task_env) to the PDK/host so a plugin can compute precedence, include moon/proto vars, and run near execution. Toolchain plugins (or a new task plugin type) could implement it; the runner/expander would merge returned env/env_files and skip .local in CI. This could also address [feature] defered dotenv evaluation #2151 (deferred timing) and [feature] Provide access to moon environment variables while expanding dotenv files #1978 (inject moon/proto vars into dotenv parsing) by providing context.

Related issues and why this helps

• [feature] defered dotenv evaluation #2151 deferred dotenv evaluation: They need env files generated by upstream tasks to be visible. If env resolution happens closer to execution (core) or via a task-env hook, those files can be picked up.
• [feature] Provide access to moon environment variables while expanding dotenv files #1978 inject moon env vars into dotenv: They need moon/proto vars available during dotenv parsing. A task-env hook could pass that context, or core could inject before parsing.

Questions

• Do you prefer a built-in, opt-in core implementation or a PDK hook so plugins can handle dotenv resolution (and related requests like [feature] defered dotenv evaluation #2151/[feature] Provide access to moon environment variables while expanding dotenv files #1978)?
• Is there an intentional constraint against task-level env hooks in the current PDK/host (perf/stability/security)?
• If core is preferred, is resolving env at run time/just-in-time acceptable to support deferred dotenv and context injection?
• If PDK is preferred, should this be a new plugin type or an optional hook on toolchain plugins?

Happy to draft a design doc in whichever direction makes sense.

[milesj]

Let me think about how best to handle this. My initial thought is to just have envFile: true expand to all the files here: https://github.com/moonrepo/moon/blob/master/crates/config/src/project/task_options_config.rs#L83