diff --git a/src/content/changelog/workers/2025-08-01-dot-env-in-local-dev.mdx b/src/content/changelog/workers/2025-08-01-dot-env-in-local-dev.mdx new file mode 100644 index 00000000000000..ab8dfc084d9e69 --- /dev/null +++ b/src/content/changelog/workers/2025-08-01-dot-env-in-local-dev.mdx @@ -0,0 +1,73 @@ +--- +title: Wrangler and the Cloudflare Vite plugin support `.env` files in local development +description: Use `.env` files to provide secrets and override environment variables on the `env` object during local development. +products: + - workers +date: 2025-08-01T01:00:00Z +--- + +Now, you can use `.env` files to provide secrets and override environment variables on the `env` object during local development with Wrangler and the Cloudflare Vite plugin. + +Previously in local development, if you wanted to provide secrets or environment variables during local development, you had to use `.dev.vars` files. +This is still supported, but you can now also use `.env` files, which are more familiar to many developers. + +## Using `.env` files in local development + +You can create a `.env` file in your project root to define environment variables that will be used when running `wrangler dev` or `vite dev`. The `.env` file should be formatted like a `dotenv` file, such as `KEY="VALUE"`: + +```bash title=".env" +TITLE="My Worker" +API_TOKEN="dev-token" +``` + +When you run `wrangler dev` or `vite dev`, the environment variables defined in the `.env` file will be available in your Worker code via the `env` object: + +```javascript +export default { + async fetch(request, env) { + const title = env.TITLE; // "My Worker" + const apiToken = env.API_TOKEN; // "dev-token" + const response = await fetch( + `https://api.example.com/data?token=${apiToken}`, + ); + return new Response(`Title: ${title} - ` + (await response.text())); + }, +}; +``` + +## Multiple environments with `.env` files + +You may be using [Cloudflare Environments](/workers/wrangler/environments/) to deploy different versions of a Worker with distinct environment variables. For instance, you may have a production and staging environment. + +To set different environment variables for each Cloudflare Environment, create files named `.env.`. + +When you use `wrangler --env ` or `CLOUDFLARE_ENV= vite dev`, the corresponding environment-specific file will also be loaded and merged with the `.env` file. + +For example, if you want to set different environment variables for the `staging` environment, you can create a file named `.env.staging`: + +```bash title=".env.staging" +API_TOKEN="staging-token" +``` + +When you run `wrangler dev --env staging` or `CLOUDFLARE_ENV=staging vite dev`, the environment variables from `.env.staging` will be merged onto those from `.env`. + +```javascript +export default { + async fetch(request, env) { + const title = env.TITLE; // "My Worker" (from `.env`) + const apiToken = env.API_TOKEN; // "staging-token" (from `.env.staging`, overriding the value from `.env`) + const response = await fetch( + `https://api.example.com/data?token=${apiToken}`, + ); + return new Response(`Title: ${title} - ` + (await response.text())); + }, +}; +``` + +## Find out more + +For more information on how to use `.env` files with Wrangler and the Cloudflare Vite plugin, see the following documentation: + +- [Environment variables and secrets](/workers/development-testing/environment-variables) +- [Wrangler Documentation](https://developers.cloudflare.com/workers/wrangler) +- [Cloudflare Vite Plugin Documentation](https://developers.cloudflare.com/workers/wrangler/vite)