--- description: Using Cloudflare environments with the Vite plugin title: Cloudflare Environments image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/workers/llms.txt > Use this file to discover all available pages before exploring further. # Cloudflare Environments Last updated Aug 24, 2026|Copy as Markdown|[View as Markdown](https://mchen-ai-models-sync.previews.developers.cloudflare.com/workers/vite-plugin/reference/cloudflare-environments/index.md)|[Agent setup](https://mchen-ai-models-sync.previews.developers.cloudflare.com/agent-setup/) A Worker config file may contain configuration for multiple [Cloudflare environments](https://mchen-ai-models-sync.previews.developers.cloudflare.com/workers/wrangler/environments/). With the Cloudflare Vite plugin, you select a Cloudflare environment at dev or build time by providing the `CLOUDFLARE_ENV` environment variable. Consider the following example Worker config file: ```jsonc { "$schema": "./node_modules/wrangler/config-schema.json", "name": "my-worker", // Set this to today's date "compatibility_date": "2026-08-24", "main": "./src/index.ts", "vars": { "MY_VAR": "Top-level var" }, "env": { "staging": { "vars": { "MY_VAR": "Staging var" } }, "production": { "vars": { "MY_VAR": "Production var" } } } } ``` ```toml "$schema" = "./node_modules/wrangler/config-schema.json" name = "my-worker" # Set this to today's date compatibility_date = "2026-08-24" main = "./src/index.ts" [vars] MY_VAR = "Top-level var" [env.staging.vars] MY_VAR = "Staging var" [env.production.vars] MY_VAR = "Production var" ``` If you run `CLOUDFLARE_ENV=production vite build` then the output `wrangler.json` file generated by the build will be a flattened configuration for the 'production' Cloudflare environment, as shown in the following example: ```json { "name": "my-worker", "compatibility_date": "2025-04-03", "main": "index.js", "vars": { "MY_VAR": "Production var" } } ``` Notice that the value of `MY_VAR` is `Production var`. This flattened configuration combines [top-level only](https://mchen-ai-models-sync.previews.developers.cloudflare.com/workers/wrangler/configuration/#top-level-only-keys), [inheritable](https://mchen-ai-models-sync.previews.developers.cloudflare.com/workers/wrangler/configuration/#inheritable-keys), and [non-inheritable](https://mchen-ai-models-sync.previews.developers.cloudflare.com/workers/wrangler/configuration/#non-inheritable-keys) keys. Note The default Vite environment name for a Worker is always the top-level Worker name. This enables you to reference the Worker consistently in your Vite config when using multiple Cloudflare environments. See [Vite Environments](https://mchen-ai-models-sync.previews.developers.cloudflare.com/workers/vite-plugin/reference/vite-environments/) for more information. Cloudflare environments can also be used in development. For example, you could run `CLOUDFLARE_ENV=development vite dev`. It is common to use the default top-level environment as the development environment and then add additional environments as necessary. Note Running `vite dev` or `vite build` without providing `CLOUDFLARE_ENV` will use the default top-level Cloudflare environment. As Cloudflare environments are applied at dev and build time, specifying `CLOUDFLARE_ENV` when running `vite preview` or `wrangler deploy` will have no effect. ## Secrets in local development Caution Do not use `vars` to store sensitive information in your Worker's Wrangler configuration file. Use secrets instead. Put secrets for use in local development in either a `.dev.vars` file or a `.env` file, in the same directory as the Wrangler configuration file. Note You can use the [secrets configuration property](https://mchen-ai-models-sync.previews.developers.cloudflare.com/workers/wrangler/configuration/#secrets-configuration-property) to declare which secret names your Worker requires. When defined, only the keys listed in `secrets.required` are loaded from `.dev.vars` or `.env`. Additional keys are excluded and missing keys produce a warning. Note Choose to use either `.dev.vars` or `.env` but not both. If you define a `.dev.vars` file, then values in `.env` files will not be included in the `env` object during local development. These files should be formatted using the [dotenv โ†—](https://hexdocs.pm/dotenvy/dotenv-file-format.html) syntax. For example: ```bash SECRET_KEY="value" API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" ``` Do not commit secrets to git The `.dev.vars` and `.env` files should not be committed to git. Add `.dev.vars*` and `.env*` to your project's `.gitignore` file. To set different secrets for each Cloudflare environment, create files named `.dev.vars.` or `.env.`. When you select a Cloudflare environment in your local development, the corresponding environment-specific file will be loaded ahead of the generic `.dev.vars` (or `.env`) file. * When using `.dev.vars.` files, all secrets must be defined per environment. If `.dev.vars.` exists then only this will be loaded; the `.dev.vars` file will not be loaded. * In contrast, all matching `.env` files are loaded and the values are merged. For each variable, the value from the most specific file is used, with the following precedence: * `.env..local` (most specific) * `.env.local` * `.env.` * `.env` (least specific) Controlling \`.env\` handling It is possible to control how `.env` files are loaded in local development by setting environment variables on the process running the tools. * To disable loading local dev vars from `.env` files without providing a `.dev.vars` file, set the `CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV` environment variable to `"false"`. * To include every environment variable defined in your system's process environment as a local development variable, ensure there is no `.dev.vars` and then set the `CLOUDFLARE_INCLUDE_PROCESS_ENV` environment variable to `"true"`. This is not needed when using the [secrets configuration property](https://mchen-ai-models-sync.previews.developers.cloudflare.com/workers/wrangler/configuration/#secrets-configuration-property), which loads from `process.env` automatically. ## Combining Cloudflare environments and Vite modes You may wish to combine the concepts of [Cloudflare environments](https://mchen-ai-models-sync.previews.developers.cloudflare.com/workers/wrangler/environments/) and [Vite modes โ†—](https://vite.dev/guide/env-and-mode.html#modes). With this approach, the Vite mode can be used to select the Cloudflare environment and a single method can be used to determine environment specific configuration and code. Consider again the previous example: ```jsonc { "$schema": "./node_modules/wrangler/config-schema.json", "name": "my-worker", // Set this to today's date "compatibility_date": "2026-08-24", "main": "./src/index.ts", "vars": { "MY_VAR": "Top-level var" }, "env": { "staging": { "vars": { "MY_VAR": "Staging var" } }, "production": { "vars": { "MY_VAR": "Production var" } } } } ``` ```toml "$schema" = "./node_modules/wrangler/config-schema.json" name = "my-worker" # Set this to today's date compatibility_date = "2026-08-24" main = "./src/index.ts" [vars] MY_VAR = "Top-level var" [env.staging.vars] MY_VAR = "Staging var" [env.production.vars] MY_VAR = "Production var" ``` Next, provide `.env.staging` and `.env.production` files: ```sh CLOUDFLARE_ENV=staging ``` ```sh CLOUDFLARE_ENV=production ``` By default, `vite build` uses the 'production' Vite mode. Vite will therefore load the `.env.production` file to get the environment variables that are used in the build. Since the `.env.production` file contains `CLOUDFLARE_ENV=production`, the Cloudflare Vite plugin will select the 'production' Cloudflare environment. The value of `MY_VAR` will therefore be `'Production var'`. If you run `vite build --mode staging` then the 'staging' Vite mode will be used and the 'staging' Cloudflare environment will be selected. The value of `MY_VAR` will therefore be `'Staging var'`. For more information about using `.env` files with Vite, see the [relevant documentation โ†—](https://vite.dev/guide/env-and-mode#env-files). Was this helpful? YesNo ## On this page [![](https://mchen-ai-models-sync.previews.developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://mchen-ai-models-sync.previews.developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/workers/vite-plugin/reference/cloudflare-environments/#page","headline":"Cloudflare Environments ยท Cloudflare Workers docs","description":"Using Cloudflare environments with the Vite plugin","url":"https://developers.cloudflare.com/workers/vite-plugin/reference/cloudflare-environments/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-08-24","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ```