Composing environment variables

[tyleralbee]

Summary

I am trying to wrap my head around how environment variables should be handled. I understand that instead of having a single .env file in the root of the repository, .env files should be kept in the packages where they're used:

Using a .env file at the root of the repository is not recommended. Instead, we recommend placing your .env files into the packages where they're used.

First: is the above usage of "packages" is referring to Application Packages, Internal Packages, or both?

The surrounding context leads me to believe that "packages" is referring to Application Packages:

This practice more closely models the runtime behavior of your applications since environment variables exist in each application's runtime individually.

It makes sense to me that the environment variables would be application-scoped, but please correct me if I'm wrong. To be clear, my understanding is that the repository should look like this:

my-repository
├── apps
│   └── app-a
│   │   └── .env
│   │   └── .env.development
│   │   └── ... ... ...
│   │   └── package.json
│   └── app-b
│   │   └── .env
│   │   └── .env.development
│   │   └── ... ... ...
│   │   └── package.json
└── packages
│   └── package-a
│   └── package-b
└── package.json
└── README.md

In the structure above, app-a and app-b have .env files, whereas package-a, package-b, and the repository root do not.

In some cases, I feel it would make sense for my .env files to be co-located with an Internal Packages. For example, I have a specific-db Internal Package which is always looking for SPECIFIC_DB_CONNECTION_URL. This variable is dependent on the environment; that is, app-a and app-b will pass the same SPECIFIC_DB_CONNECTION_URL in production. In addition, specific-db has code generation scripts that rely on SPECIFIC_DB_CONNECTION_URL.

If I structure my repository such that my .env files are co-located with specific-db:

my-repository
├── apps
│   └── app-a
│   └── app-b
└── packages
│   └── specific-db
│   |   └── scripts
│   |   |   └── codegen.ts
│   │   └── .env
│   │   └── .env.development
│   │   └── ... ... ...
│   │   └── package.json
│   └── package-b
└── package.json
└── README.md

How would I go about composing the environment variables for app-a from the environment variables in specific-db? Is there a better way than duplicating the .env files from specific-db and/or writing codegen to keep them in sync?

Unrelated question: what's a use-case in which globalEnv makes sense to use over task-specific env? Can someone give me an example of an environment variable that should result in a lint task missing cache on change?

References

• Using environment variables
• System environment variables
• Deployment using the wrong environment variables

[anthonyshew]

Good question, and you're thinking about things attentively. I appreciate the thoughtfully worded question(s).

The way that I like thinking about it is: When I run my code locally, I'm simulating what happens in production. You don't run packages, you run applications that are composed of packages (which is something you correctly alluded to).

With that mental model, you start to realize that a package has no independent runtime. It only runs within the context of an application. So, if I want to model that locally, that would mean I only use .env files in applications.

There's an exception: If you're running scripts directly in packages that require environment variables, you might be forced to put a .env file into a package. Prisma comes to mind. This is indeed a little awkward and breaks the idealistic model I was describing earlier, but is not impossible to do and create great workflows with.