Environment variables are automatically expanded

[Renato66]

Error

I encountered some trouble when trying to set up my environment, as mentioned in this issue. Specifically, when I have an .env file with a line like API_KEY=$ds12re==, the value of the API_KEY becomes just == when reading it using Bun via bun --print process.env.

Suggestion

1. String Concatenation

In JavaScript, environment variables are often used in combination, and a common scenario is string interpolation within .env files. For example, something like:

DB_USER=postgres
DB_PASSWORD=secret
DB_HOST=localhost
DB_PORT=5432
DB_URL=postgres://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}

In this case, if any of the referenced variables (DB_USER, DB_PASSWORD, etc.) aren't defined in the .env file or the environment, the interpolation won't behave as expected.

2. Error Handling

If a variable used in the .env file isn't defined, it would be helpful to throw an error or at least provide clear feedback. This way, developers can catch misconfigurations early.

3. Logs

If an undefined variable is encountered, Bun could log a warning indicating that the variable wasn't defined. This could help prevent silent errors during development.

4. Visual Indicators

Another useful addition would be to visually warn or flag the need to escape certain characters or provide context when using special syntax in the .env file. A simple example is having an indicator for unresolved variables, something like this:

5. Documentation Update

If no changes are made to how Bun handles environment variables, it would be helpful to update the official documentation to clarify this behavior. This could go under Bun’s guide on environment variables, explaining how Bun processes .env files, especially in scenarios where variables aren't properly scoped or concatenation occurs.

This clarification would greatly help developers avoid unexpected behavior and make troubleshooting easier when working with Bun's environment variables.

6. Opt in

Not have the expansion activated by default and let people who want to utilize it, opt-in.

[hubdidub]

Yepp, the variable expansion caused me problems too when I started using Bun because I didn't know about it at first. (Didn't know this was a thing at all). I bet it has caused headaches for many people.
Maybe it would be helpful to mention it in the guide.
But in the docs, there is already a section about it.

The problem with warning about undefined variables is that you are not only able to reference the variables defined inside the .env file, you can reference any environment variable on the system. And since you can't really know where the application is deployed, I guess it doesn't really make much sense.
If somebody does mean to reference a variable outside of the .env file, a warning would be annoying and we would need a way to turn it off.
But on the other hand, you can argue that running into this pitfall if you don't know about it is annoying too 🤔

I would say a better solution would be to not have the expansion activated by default and let people who want to utilize it, opt-in.