Add dotEnv to turbo.json

[nathanhammond]

Enable configuring .env files inside of turbo.json. These are addition-only to file hashes, and enables specifying load order for cache distinctions.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
examples-basic-web	🔄 Building (Inspect)			May 19, 2023 10:28am
examples-vite-web	🔄 Building (Inspect)			May 19, 2023 10:28am
turbo-site	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 19, 2023 10:28am

8 Ignored Deployments

Name	Status	Preview	Comments	Updated (UTC)
examples-cra-web	⬜️ Ignored (Inspect)			May 19, 2023 10:28am
examples-designsystem-docs	⬜️ Ignored (Inspect)			May 19, 2023 10:28am
examples-gatsby-web	⬜️ Ignored (Inspect)			May 19, 2023 10:28am
examples-kitchensink-blog	⬜️ Ignored (Inspect)			May 19, 2023 10:28am
examples-native-web	⬜️ Ignored (Inspect)			May 19, 2023 10:28am
examples-nonmonorepo	⬜️ Ignored (Inspect)			May 19, 2023 10:28am
examples-svelte-web	⬜️ Ignored (Inspect)			May 19, 2023 10:28am
examples-tailwind-web	⬜️ Ignored (Inspect)			May 19, 2023 10:28am

[vercel]

Someone is attempting to deploy a commit to the Vercel Team on Vercel.

A member of the Team first needs to authorize it.

[mehulkar]

• Is there any difference between using this key and the inputs key?
• do we want to throw an error if it's specified in both places?
• What happens if you add inputs: [!.env]?

[nathanhammond]

@mehulkar

Is there any difference between using this key and the inputs key?

Yes, specifying the first glob in inputs toggles off the "include everything in the git index inside this package's folder" default. (caveats apply, but they're bugs: see Slack thread)

Having an alternative method to specify this does a few things:

• By simple existence causes people to actively consider their .env files. Sometimes simply naming a thing or pattern makes the UX better. (For context: you could do 100% of what Ember Services could do when introduced using vanilla Ember things if you knew the incantation; same applies here.)
• Creates a configuration location that does not toggle off the default behavior.
• Gives us some rails to ride on for future "help me not screw up .env files" behavior.

do we want to throw an error if it's specified in both places?

No, because it doesn't make any material difference if you include it in both places (they get combined into the same list of hashed files).

What happens if you add inputs: [!.env]?

Given this configuration:

{
  "inputs": ["**", "!.env*"],
  "dotEnv": [".env.local", ".env"]
}

The file hash will include .env and .env.local (if present on disk). This is a conservative default; it results in over-partitioning in the event of misconfiguration.

In one proposed possible future variant turbo --dotenv will load environment variables from those locations and not merge the files into the task hash; instead encouraging you to specify your environment variable dependencies using env (and passthroughEnv). This would make the configuration you describe appear sensible, but would already be configured for you by turning all of dotEnv to excludes when that flag is present.

(Including the entire file and the entire fallback chain is already over-partitioning; this would enable precise targeting.)

[nathanhammond]

Reviewer's Guide!

[nathanhammond]

This is the basic logic for reading the inputs into the tasks.

[nathanhammond]

And this is the basic logic for reading the inputs into the global state.

Combined with the task work, this covers the input. Everything else is plumbing.

[nathanhammond]

These tests are just one each of:

• {}
• { "(global)DotEnv": null }
• { "(global)DotEnv": [] }
• { "(global)DotEnv": ["populated"] }

They also check that it can serialize back out to ensure that we don't break prune.

[nathanhammond]

The existing hash mechanism hard errors for nonexistent files; that's because we already do an existence check prior to attempting to hash with the glob walk.

The dotEnv field does not support globbing, we don't want this to error for files that don't exist, and we can't rely on git since a fair chunk of .env files will not be committed, so we plumb it directly through to manual hashing.

[nathanhammond]

These files get dropped into the files that already get hashed from globalDeps.

[nathanhammond]

And we repeat the task for individual task hashes.

[nathanhammond]

Makes sure that the specified path is not an absolute path.

[mehulkar]

The code looks good, but I'm having trouble getting on board with special casing a certain kind of file. Have we considered any alternative ways of doing this? For example an $auto option came up a while ago, maybe a similar inputs: ['$dotenv'] could work? This is not as discoverable as what you have here, but thinking out loud.

Specifically, I'm concerned about:

• Two affordances for specifying file inputs
• Other env var declaration tools than dotenv (now or in the future)
• Other ways of specifying dotenv config that don't match these patterns
• Abusing this feature to "always include a file" that has nothing to do with dotenv
• API expansion in general

I'm also thinking of the auto inclusion of package.json and turbo.json when inputs are specified. That's another exception to inputs that applies under "some but not all" circumstances, and is a totally different mechanism than the one for dotenv files.

In any case, I don't know of any conversations or RFCs where we decided on this implementation, so I don't love having this conversation after the code is already done. I'll assume that you've already done due diligence, but wanted to give a "real" review.