Vite Environments

The Vite Environment API ↗, released in Vite 6, is the key feature that enables the Cloudflare Vite plugin to integrate Vite directly with the Workers runtime. It is not necessary to understand all the intricacies of the Environment API as an end user, but it is useful to have a high-level understanding.

Default behavior

Vite creates two environments by default: client and ssr. A front-end only application uses the client environment, whereas a full-stack application created with a framework typically uses the client environment for front-end code and the ssr environment for server-side rendering.

By default, when you add a Worker using the Cloudflare Vite plugin, an additional environment is created. Its name is derived from the Worker name, with any dashes replaced with underscores. This name can be used to reference the environment in your Vite config in order to apply environment specific configuration.

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.

Environment configuration

In the following example we have a Worker named my-worker that is associated with a Vite environment named my_worker. We use the Vite config to set global constant replacements for this environment:

wrangler.jsonc

{
  "name": "my-worker",
  "compatibility_date": "2025-04-03",
  "main": "./src/index.ts"
}

wrangler.toml

name = "my-worker"
compatibility_date = "2025-04-03"
main = "./src/index.ts"

vite.config.ts

import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
  environments: {
    my_worker: {
      define: {
        __APP_VERSION__: JSON.stringify("v1.0.0"),
      },
    },
  },
  plugins: [cloudflare()],
});

For more information about Vite's configuration options, see Configuring Vite ↗.

The default behavior of using the Worker name as the environment name is appropriate when you have a standalone Worker, such as an API that is accessed from your front-end application, or an auxiliary Worker that is accessed via service bindings.

React Router v7

If you are using the Cloudflare Vite plugin with React Router v7 ↗, then your Worker is used for server-side rendering and tightly integrated with the framework. To support this, you should assign it to the ssr environment by setting viteEnvironment.name in the plugin config.

vite.config.ts

import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";
import { reactRouter } from "@react-router/dev/vite";

export default defineConfig({
  plugins: [cloudflare({ viteEnvironment: { name: "ssr" } }), reactRouter()],
});

This merges the Worker's environment configuration with the framework's SSR configuration and ensures that the Worker is included as part of the framework's build output.