(in the meantime, we've reorganized all our env vars to start with APP_* or PUBLIC_*. this means we now have a manageable "env" array in turbo.json and won't have to remember to maintain it as we add new vars. strict mode here we come.)

I've been thinking about if we could do something like warning when things are missing.

• When working locally, we can scan your .env* files and give you a warning when those variables aren't present in the env key.
• The addition of some sort of turbo scan --env that builds off of the current turbo scan to read your source code for instances of process.env.*. This could print what's missing from the env key (although we still may not be able to find everything, as you'll see in the last paragraph). Additionally, you could run something similar in CI and we could either hard error when things are definitely missing, or warn.

My concern is that inferring env can be dangerous unless we can figure out how to get it exactly right, every time. The cost of over-caching is extremely high since, if it gets messed up, you can ship your preview environment variables to production. So unless there's an absolutely foolproof way of inferring what you're using, that inference is potentially dangerous.

It's also worth noting that there can be environment variables that you don't use in your source code that can drastically affect runtime behavior, like Vitest's watch mode. In this case, we can't infer anything from your source code and we would be caching the wrong thing.

I like the idea of being able to validate env config. That said, I'd be mad impressed if scanning source code was viable. I don't think it is though; just to get started, we have:

• process.env.MY_VAR
• const { MY_VAR } = process.env
• const env = z.object({...}).parse(process.env)
• repeat above for import.meta.env
• framework specific env's, like SvelteKit's $env/static/private import module (and its dynamic & public counterparts) (example)
• envs used in bash scripts
• envs from CI/CD configs, such as GitHub actions (on second thought, likely not relevant for Turborepo commands?)
• env usage in other languages (python/go/rust/etc., unsure which are commonly paired with Turborepo)

Realistically, I assume support for src scanning would probably only cover a narrow slice, to the point where it may not be useful in the more complex setups where it's needed the most.

Scanning .env files and comparing that to a package + task config could help for some automatic checks. To be useful long term, this would need to be automated; otherwise, if one forgets to add an env to a turbo file, they'll likely also not remember to manually run the check.
But, for this to be considered viable, wouldn't that necessitate .env files be a valid source? At that point, why not allow inferring from them, too?

By the way, just to clarify: In this proposal, scanning .env files would not be the default behaviour. It would be a manual opt-in config, only relevant when .env files are present and contain the bulk of env vars. Even then it's not intended as an all-or-nothing replacement, but as a base, that can be merged with Turbo's default envs, and additional manual envs (e.g. CI, MODE, etc.).

The various places you'll find env vars is a good point, and not covering enough is something I've worried about with eslint-plugin-turbo. Thanksfully, we haven't heard feedback that it's a problem in practice (but that might be just dumb luck).

if one forgets to add an env to a turbo file, they'll likely also not remember to manually run the check.

That was why I mentioned being able to run turbo scan --env (or something) in CI. You'd fail the check in that case.

But, for this to be considered viable, wouldn't that necessitate .env files be a valid source? At that point, why not allow inferring from them, too?

My instinct is that there would be a difference in our users' expectations with these two proposals:

• Auto-infer from .env would effectively mean "We're going to automatically infer your environment variables." If a variable gets missed, it's easy to blame Turborepo. I would expect to hear "You said you were going to handle it?!" and, well, they'd be right. If we're going to give people the impression that they don't have to worry about it anymore, we would have to be perfect, and I don't think we'd be able to make it there.
• Preemptive scanning is something more aptly described as "we're going to be helpful but it's still your responsibility at the end of the day." It's certainly not as beautiful of a solution, I acknowledge, but it's also closer to what we can realistically do in our part of your stack.

(I'll also note that I like your idea generally but I'm trying to draw out the cases where it doesn't work to see if the gaps can be filled. This feature is exactly something that we've discussed amongst ourselves on core and the weaknesses have been difficult to work through and justify as something shippable.)

{
  "dangerouslyInferFromDotEnvAtYourOwnRiskDont@Me": [".env.example"],
}

/s

Yeah, I see your point; there's the risk users will set this without the necessary understanding. E.g. they might set this using their git-ignored env file, and then wonder why their envs are all undefined in CI/CD.

I'd like to think that could be improved with docs, naming, and examples, but someone's still bound to miss them. (Case in point, when we were upgrading to v2: I had already prepped a repro and almost opened an issue, wondering why globalEnv wasn't working—until I found this already documented. 😅 It already has "global" in the name, and I still misinterpreted it as "applicable to all tasks (in a given package)".)

A scan feature might be less subject to misinterpretation. While that won't make configuration any easier or less verbose, it could at least help catch missing vars. (Unsure if we'd continuously use that feature ourselves, but others may have more use for it.)