Proposal: Standardize .env file support for Cloudflare Workers during local development

[korinne]

Standardize .env file support for Cloudflare Workers during local development

Hi 👋

Our team is focused on improving the local development experience on Cloudflare Workers, and we’d love your feedback on the following proposal. This proposal outlines plans to support loading environment variables via .env files during local development (whether you’re using wrangler dev directly or through integrations like the Cloudflare Vite plugin), allowing you to configure environment variables and secrets in familiar ways.

Background

Many developers are accustomed to configuring environment variables and secrets in a .env file, expecting a tool (such as the dotenv package) to load these into an application’s accessible environment during local execution. The primary purpose of .env is to keep configuration separate from application code, a principle promoted by the third factor “Config” in the Twelve-Factor App paradigm.

As projects grow, managing configuration for different environments (dev , staging , production etc) and individual developer preferences get more complex. It’s becoming more common to now commit .env files with shared configuration settings across a given project, and use specific file naming conventions for a layered approach. For example:

• env.local: This file is intended for local development overrides/secrets that an individual developer can set, and should not be committed to version control.

• Environment-specific files (.env.staging , .env.production): These files are used to define shared, non-sensitive default configurations for specific environments.

In short, many ecosystems and libraries have standardized on how .env files are loaded, and many developers start projects on Cloudflare Workers expecting similar file handling. However, environment variables and secrets are configured differently for Workers applications – making the platform feel less straightforward and resulting in requests like this one. We’ll spend a moment explaining why things are different on Workers, and then lay out our proposal on how to meet developers where they are.

Why it’s different on Workers

Cloudflare Workers run in a different runtime (workerd) that is separate from the tooling environment that Wrangler relies on (Node.js). Because of this, we currently support two different ways to set environment variables at runtime or at buildtime.

• Runtime variables: To make environment variables available to a Worker’s env object (its environment bindings), you can set project-level environment variables as vars in Wrangler configuration (which is checked into version control). For runtime secrets or variables that are strictly for local development and should not be committed to version control (similar to env.local ), Workers supports a.dev.vars file in the root of your project. This file is loaded when you run a local dev session and any variables are added to the env object of your Worker. This .dev.vars file is today’s primary (and Cloudflare-specific) method for injecting these local-only values directly into your Worker’s runtime context.

• Buildtime variables: To configure the build process and tools with environment variables (such as Wrangler itself and Node.js), you can set system environment variables in a .env file. Currently, Wrangler reads .env files and merges their contents with the process environment variables for this purpose only. These variables are used to modify how Wrangler the tool works (ex: WRANGLER_LOG="debug") and are not passed to your Worker's env object at runtime. This specific use of .env files has confused some users who expect variables defined there to also be available to their Worker code at runtime.

Proposal

To better meet expectations, align with ecosystem standards, and provide a more intuitive experience, we propose introducing support for .env files for configuring your Worker’s runtime environment during local development. This is an alternative approach to the existing .dev.vars file usage.

This means you will have two options for specifying local environment variables:

1. Using .env files: You can define local environment variables in a familiar .env file, including environment specific files (such as env.staging). You’ll benefit from local overrides and variable expansion, whether you’re using Wrangler directly or the Cloudflare Vite plugin. This method will be active if no relevant .dev.vars file is detected for your current development context.

2. Using .dev.vars files (Existing method): If a .dev.vars file (or its environment-specific counterpart like .dev.vars.staging) is present for your current development context, the system will exclusively use it to load variables into your Worker’s runtime context. This ensures backwards compatibility for existing projects, and provides a clear way to opt-out of the .env file loading mechanism if desired. In this scenario, .env files will not be used to populate the Worker's env object (though they may still configure Wrangler itself via specially prefixed variables like WRANGLER_LOG).

File loading and precedence

The source and priority of your Worker's runtime variables during local development depend on which files are present:

Scenario 1: Running local dev with no specified `--env`

Using .env files
(This applies when no relevant .dev.vars file is present)

1. The system will load .env files.
2. .env.local is loaded first (if it exists).
3. Then, .env is loaded (if it exists).
4. Variables from these files are merged, with .env.local taking precedence over .env in case of conflicts.
5. Any variables from the merged .env files prefixed with MINIFLARE_, WRANGLER_ or CLOUDFLARE_ are filtered out and not added to the Worker’s env object. They are used to configure Wrangler the tool.
6. Project-level vars from Wrangler configuration are loaded, with the merged variables from .env.local and .env taking precedence.

Using .dev.vars
(This applies when a relevant .dev.vars file is present and takes precedence)

1. dev.vars is loaded
2. Variables from .env (or any other `.env.*` files) are not loaded into the Worker’s env object. They may still be used to configure Wrangler itself if they have WRANGLER_ or CLOUDFLARE_ prefixes.
3. Project-level vars from Wrangler configuration are loaded, with .dev.vars taking precedence in case of conflicts.

Scenario 2: Running local dev with a specified environment (such as --env=staging)

Using .env files
(This applies when no relevant .dev.vars or .dev.vars.staging files are present)

1. The system will load .env files in the following order of precedence (the more specific the file, the higher the precedence:
   • .env.staging.local
   • .env.staging
   • .env.local
   • .env
2. All loaded variables from the applicable .env files (.env.staging.local, .env.staging,.env.local, .env) are merged into a single collection, respecting the precedence order where more specific files override less specific ones.
3. Any variables prefixed with MINIFLARE_, WRANGLER_ or CLOUDFLARE_ are filtered out.
4. Project-level vars from the Wrangler configuration (including those specific to the staging environment, if defined) are loaded, with the merged variables from the .env.* files taking precedence.

Using.dev.vars or .dev.vars.staging
(This applies when a relevant .dev.vars or .dev.vars.staging file is present and takes precedence)

1. If .dev.vars.staging exists, it is loaded. Only values from the most specific file are loaded.
2. If .dev.vars exists and no .dev.vars.staging was found, dev.vars is loaded.
3. Variables from any .env.* files are not loaded into the Worker’s env object.
4. Project-level vars from the Wrangler configuration (including those specific to the staging environment, if defined) are loaded, with the variables from the active .dev.vars file (ex: .dev.vars.staging or .dev.vars) taking precedence.

Notes on merging and precedence for .env files

• As mentioned above, more specific .env files override less specific ones. Environment-specific files override general ones.
  • Example (highest to lowest precedence): .env.staging.local -> .env.staging -> .env.local -> .env
• .env files and .dev.vars files are loaded differently.
  • .env files: Following common practice, variables will be merged from the hierarchy of .env files.
  • .dev.vars files: To maintain existing behavior, only the single, most specific .dev.vars file (such as .dev.vars.staging) will take precedence and be used exclusively (no variable merging).
• Actual OS environment variables (such as process.env.NODE_DEBUG ) will not be added to the Worker’s env object. This includes variables added to shell commands such as NODE_DEBUG=foo wrangler dev.
• MINIFLARE_, WRANGLER_ and CLOUDFLARE_ prefixed variables are strictly for configuring Wrangler and will not be passed to the Worker's env object, regardless of the file they originate from (.env or .dev.vars )
  • While ideally this filtering would also apply to .dev.vars files, doing so would be a breaking change for existing .dev.vars users, so this filtering currently applies when .env files are the source for Worker runtime variables.

Variable expansion

We will also support variable expansion in .env files. This means you can reference other variables defined with the same file or previously loaded .env files (respecting the precedence order). For example:

BASE_URL=http://localhost:8787 
API_ENDPOINT=${BASE_URL}/api/v1 
ANOTHER_KEY=$OTHER_KEY # Also works with $

Variable expansion is only available for .env files and is not supported for .dev.vars files. Additionally, variable expansion does not extend to the vars defined in Wrangler configuration. For example, if you have the following in a wrangler.json :

{
"vars": { "API_ENDPOINT": "${BASE_URL}/api/v1"
}

This will be used verbatim and not expanded, even if there is a .env file containing BASE_URL.
We do not plan to support command substitution.

Integration with the Cloudflare Vite Plugin

The proposed .env file handling will extend to projects using the Cloudflare Vite plugin, ensuring a consistent experience. Here’s how it will generally work:

• Vite Modes and Cloudflare environments: The Cloudflare Vite plugin uses a CLOUDFLARE_ENV environment variable to indicate which “Cloudflare environment” to use. This can be defined within your .env files (for example, in .env.staging you might set CLOUDFLARE_ENV=staging) to bridge Vite's concept of "modes" with Cloudflare Workers environments. This part of the Vite plugin's behavior will remain.
• Local development: Vite itself will load .env files (.env, .env.staging, etc) to populate import.meta.env for build-time replacements and for its own configuration.
  • The Cloudflare Vite plugin will then apply the same logic described in this proposal for loading variables into your Worker's env object. If no .dev.vars file is present for the target Cloudflare environment, the plugin will use the relevant, merged .env files (respecting the full precedence order ex:.env.staging, .env) as the source for your Worker's runtime variables, filtering out MINIFLARE_, CLOUDFLARE_ and WRANGLER_ prefixes. These variables will also support expansion.
• Building (vite build): When you build your project for deployment, Vite will load .env files according to its mode (typically "production") for build-time operations (like replacing import.meta.env.VITE_XXX). Runtime variables for your Worker declared in .env files during local development cannot be accessed via the Worker’s env in production. Deployed Workers will continue to source their runtime variables from your Wrangler configuration and secrets uploaded via wrangler secret put or the Cloudflare dashboard. This ensures that local development conveniences from .env files do not inadvertently become the source of truth for production runtime configuration.

Considerations:

• The wrangler types command currently generates types for vars bindings from the values in .dev.vars when generating the Env interface. This would now include any non-prefixed variables found in the merged .env (and .env.<environment> files, which may not be expected / make the Env type more verbose.
• We are still in discussions about how .env files will be handled in monorepo setups, and will follow-up on this proposal.

Call to action

• Please provide feedback on the above proposal, and let us know if this would improve your current development experience. Thank you in advance!

[remorses]

In my opinion Workers should inject current shell environment variables into the worker, this way you can use your own approach to add env variables like Doppler, Infiscal or .env files via the dotenv-cli. This is also the most obvious way to add env variables from a user perspective, simply add env variables to the shell, like you do in Node or any other runtime.

Right now i use doppler to manage env variables and i have to run a script to download the env variables to a .dev.env file, if you added support for .env i would need to do the same but download them to an .env file. What i would like to do instead is for workers to use my shell environment so i can just use the doppler run command to run wrangler with my secrets.

Another possible solution would be to have a default worker environment called development and inject secrets from that env into the worker. This way the user would use the Cloudflare dashboard to add env variables.

[korinne]

Thanks everyone for your feedback -- both publicly and privately! Some updates here:

• Based on feedback, we won't be stripping out variables prefixed with MINIFLARE_, WRANGLER_, or CLOUDFLARE_

• We are considering including an environment variable such as CLOUDFLARE_INCLUDE_PROCESS_ENV that when set to true, would mean all the env vars from process.env would be included in the .env parsing. @remorses would love your thoughts on if this is sufficient (I know it's more explicit / opt-in this case, but we are discussing if this should be set to true by default).

Will follow-up about timelines shortly.

[remorses]

CLOUDFLARE_INCLUDE_PROCESS_ENV that when set to true, would mean all the env vars from process.env would be included in the .env parsing

Does this mean you still need an .env file to use the shell env variables? Or can I just run CLOUDFLARE_INCLUDE_PROCESS_ENV=true SOME_VAR=x wrangler dev to make wrangler inject SOME_VAR into process.env?

[petebacondarwin]

Good question. I think that the existence of this environment variable would be enough to tell Wrangler to pull in the process.env values. But that would require this to be opt-in. Otherwise the default for people who have neither .dev.vars nor .env files would be for the entire process.env to be dumped into their env object, which would be a breaking change.

Does that work for you?

[remorses]

yes that works for me, I will add CLOUDFLARE_INCLUDE_PROCESS_ENV in Doppler so I can simply run doppler run -- wrangler dev

[Cherry]

Very excited about this.

My only real concern is with "Any variables from the merged .env files prefixed with MINIFLARE_, WRANGLER_ or CLOUDFLARE_ are filtered out and not added to the Worker’s env object. They are used to configure Wrangler the tool.".

Technically I completely understand this with wrangler/mf using .env for its config, but I both personally and at work do use CLOUDFLARE_API_AE_TOKEN etc. env vars in my worker to query cf api for things, so would have to either do a combo with .env for some and .dev.vars for others, rename my vars, or stick with .dev.vars on those workers. I'm not sure there's a perfect solution there that doesn't risk breaking someone though.

[petebacondarwin]

Based on feedback, we won't be stripping out variables prefixed with MINIFLARE_, WRANGLER_, or CLOUDFLARE_

We have agreed not to do this stripping.

[Cherry]

Whoops I missed that update, thank you! Great to hear!

[astanciu]

It would also be useful to have a command line arg (--dotEnv?) that specifies the path to a .env file. For ex, in monorepo, it's common to have a .env at the root, where you would normally start your stack from the root. But sometimes you need to run a workspace app from its own folder. Being able to reference the root .env would allow this.

[petebacondarwin]

Yes! Good call

[petebacondarwin]

Node.js is using --env-file so I propose we go with that, which also helps to distinguish with our --env option.

See https://nodejs.org/dist/latest-v22.x/docs/api/cli.html#--env-fileconfig

[petebacondarwin]

Following along with the implementation here: #9914

[petebacondarwin]

A new feature request that has just surfaced is the ability/requirement(?) to lock down which values are read from .env files by adding a new secrets: string[] field to Wrangler configuration to compliment the secrets concept already documented. In this case only values whose keys appear in this array (or as a key in the current vars property) would be read from .env files.

Advantages

1. Generated types for local dev (secret) vars can be generated purely from the git committed Wrangler config rather than relying upon potentially uncommitted .env files. This means that it would be possible to run the wrangler types command in environments where uncommited files are not present such as in CI jobs.
2. By explicitly choosing the secrets to pull in from .env files, users can avoid including vars in their Worker that are intended for build time tools (such as CLOUDFLARE_API_TOKEN).
3. Wrangler could validate when running wrangler dev that the correct vars are populated from .env files.
4. Wrangler (or the Cloudflare backend) could validate that production secrets have been deployed for a Worker to prevent accidentally deploying a Worker with missing secrets. Wrangler/Cloudflare could also warn/error if a declared secret is deleted (e.g. via wrangler secret delete).
5. We could avoid the need for CLOUDFLARE_INCLUDE_PROCESS_ENV and always pull vars that match secrets from the actual process.env.

Disadvantages

1. Users have to list keys of values that they wish to load from .env in their Wrangler config, somewhat duplicating effort.
2. This could add a bar to entry since since users would need understand about this secrets property and how it works with local dev and deployment validation.

Feedback

We are close to landing this .env file loading in Wrangler but this feature request could change things significantly - both in terms of implementation but also in terms of usage. We'd like to get a sense from the community (you!) as to whether this would be valuable or problematic for your use cases. Please try to give feedback on this before the end of this week if you can.

[CaptinKraken]

I would like to see wrangler build and deploy respect .env and instead, update the secrets command to be able to accept pointing to files. If you need a separate .env file for CI, then .env.ci or .env.staging.ci could be read from in those pipelines.

Otherwise, i'd expect wrangler secrets + .env to maybe act like dotenvx and unlock the ability to do variable expansion

[petebacondarwin]

@CaptinKraken have you tried wrangler secret bulk .env? Or are you aware of that and want to add the merging and expansion facility to that command?

[CaptinKraken]

@CaptinKraken have you tried wrangler secret bulk .env? Or are you aware of that and want to add the merging and expansion facility to that command?

Sorry, i guess i mean, let me define the file in the configuration file, wrangler.jsonc, so that it's explicit that the env file will be included, expanded, and merged.

I'd still expect .env to be included by default, but then hooking the file into secrets, would unlock this new ability.

I'm not sure this would address advantage statement 4) though.

[petebacondarwin]

Thanks for the feedback everyone. We have decided that secrets is an interesting feature in itself, independent of the .env stuff.
So we are going to continue landing the .env feature as defined in the current PR, then circle back and work on a design for the secrets feature after that has settled. We can dig into how that feature would interact with .env loading at the point but I think we would treat it as opt-in. E.g. if you don't define secrets in your config then it .env loading would continue to work as of this RFC.

[jdanyow]

I wasted like 1 hour on friday because of a incorrectly named secret so this feature would have been really helpful for me

@Ankcorn that has happened to me in the past as well. This may be of use: #2101 (comment)

[petebacondarwin]

Thank you to everyone for your input to this feature.
We have now implemented it and it has been released in [email protected] and @cloudflare/[email protected].
The docs are on their way - you can see the draft here: cloudflare/cloudflare-docs#23837

[oldbettie]

I am currious about the structure here. This sounded like a great feature but it seems perhaps I misunderstood the problem it aimed to solve.

I have about 15-20 different workers, many of them share the same environment variables and packages so I have a workers repo that contains them all within a single package.json file. My assumption was that dropping the .env file at the root of the project as the docs define would allow me to share the same env variables with all the workers in that package.

It seems perhaps thats not the case as it only works if the .env file is in the same folder as the wrangler.yaml file

[petebacondarwin]

The root of a Worker project is the directory where the Wrangler config file is found. This is where we look for the .env files.
I assume that you have lots of scripts in your package.json, like "deploy:worker-a": "wrangler deploy -c worker-a/wrangler.jsonc"?
If I understand correctly, you expected that the tooling would traverse up the directory tree looking for the nearest .env file? Or perhaps looking for the nearest package.json and then look for the .env file there? Or perhaps looking in the current working directory for a .env file?
These are possible approaches we could have taken but they all have scenarios that could confuse people.

One approach you could take, if the structure is as you say above... Rather than having wrangler.jsonc files in each worker subdirectory, you could have all the Wrangler config files at the root...

project-root
  .env
  package.json
  wrangler.worker-a.jsonc
  wrangler.worker-b.jsonc
  wrangler.worker-c.jsonc
  worker-a
    index.ts (etc)
  worker-c
    index.ts (etc)
  worker-c
    index.ts (etc)

Then in your package.json you could have:

{
  "scripts": {
    "deploy:worker-a": "wrangler deploy -c wrangler.worker-a.jsonc",
    "deploy:worker-b": "wrangler deploy -c wrangler.worker-b.jsonc",
    "deploy:worker-c": "wrangler deploy -c wrangler.worker-c.jsonc"
  }
}

[oldbettie]

Yeah correct. For example. We use Typesense/InstantSearch. We have 6-7 different workers just for typesense. Some are crons some are normal workers. However they all share the same env variables and config so I have a pnpm package specifically for those workers. Right now I have to have .dev.vars in each worker individually even though they use the same .env config.

Its pretty much exactly how you said. We have multiple run commands in the packages.json file. We then use a bash script to run them all with the crons in a bash loops because also the cron functionality locally seems to be not working for workers eather.

Deployments are fine because we use the cloudflare dashboard so its pretty straight forward. I am just trying to simplify the local development process.

Basically my hack right now is to have a .env file in the root of the project (Not where the wrangler files are as some of those are 2-3 folders deeper. Then in my bash script the first thing I do is copy the contents of said .env file to a .dev.vars file in any folder that has a wrangler.yaml file in it but this is definitly not idea and if I need to change an env variable then I have to restart the script.

[oldbettie]

These are possible approaches we could have taken but they all have scenarios that could confuse people.

I think the docs should be updated since the root of the worker directory might not be as you say the same place as the wrangler.yaml file.

I think what you said is basically what I expected. In a JS/TS project the root in my mind and I think most people is where the package.json file is. I would think it would look at least in the same directory as that file

[petebacondarwin]

Thanks for the feedback @oldbettie - I have created a docs update here cloudflare/cloudflare-docs#24447