Environment API for Frameworks | Vite

Dependency Pre-Bundling
Static Asset Handling
Building for Production
Deploying a Static Site
Env Variables and Modes
Server-Side Rendering (SSR)
Environment Instances
The Environment API is generally in the release candidate phase. We'll maintain stability in the APIs between major releases to allow the ecosystem to experiment and build upon them. However, note that some specific APIs are still considered experimental.
We plan to stabilize these new APIs (with potential breaking changes) in a future major release once downstream projects have had time to experiment with the new features and validate them.
Please share your feedback with us.
Since environments may run in different runtimes, communication against the environment may have constraints depending on the runtime. To allow frameworks to write runtime agnostic code easily, the Environment API provides three kinds of communication levels.
RunnableDevEnvironment is an environment that can communicate arbitrary JavaScript values with your application code. Importing a module returns its real, live exports (functions, class instances, and any other values), so frameworks can run their server entries directly. The implicit ssr environment and other non-client environments use a RunnableDevEnvironment by default during dev. You can guard access to the runner with the isRunnableDevEnvironment function.
Its runner is a ModuleRunner. You import modules through it with runner.import(url), which fetches, transforms, and evaluates a module from the Vite module graph (the url accepts a file path, server path, or id relative to the root) and returns the instantiated module with full HMR support. It is the modern replacement for server.ssrLoadModule, so frameworks can migrate to it to enable HMR for their SSR dev story.
Why it can communicate arbitrary values
A RunnableDevEnvironment evaluates modules in the same runtime as the Vite server, so values cross the boundary in-process instead of being serialized. This is what distinguishes it from FetchableDevEnvironment, which can only communicate through serialized Request/Response objects over the Fetch API. As a result, using a RunnableDevEnvironment requires the runner's runtime to be the same as the one the Vite server is running in.
The runner is evaluated lazily only when it's accessed for the first time. Beware that Vite enables source map support when the runner is created by calling process.setSourceMapsEnabled or by overriding Error.prepareStackTrace if it's not available.
Given a Vite server configured in middleware mode as described by the SSR setup guide, let's implement the SSR middleware using the environment API. Remember that it doesn't have to be called ssr, so we'll name it server in this example. Error handling is omitted.
When using environments that support HMR (such as RunnableDevEnvironment), you should add import.meta.hot.accept() in your server entry file for optimal behavior. Without this, server file changes will invalidate the entire server module graph:
We are looking for feedback on the FetchableDevEnvironment proposal.
FetchableDevEnvironment is an environment that can communicate with its runtime via the Fetch API interface. Since the RunnableDevEnvironment is only possible to implement in a limited set of runtimes, we recommend to use the FetchableDevEnvironment instead of the RunnableDevEnvironment.
A common reason to reach for it is a framework that wants to support a runtime that can't run Vite directly (e.g. Cloudflare Workers). A RunnableDevEnvironment can't be used there, since it requires the runner to share the Vite server's runtime so values can cross the boundary in-process. Standardizing on the Fetch API lets the framework keep a single request-handling path across all of its target runtimes: its dev middleware forwards each incoming browser request as a Request and sends the returned Response back to the browser, mirroring how the app handles requests in production.
This environment provides a standardized way of handling requests via the handleRequest method:
Vite validates the input and output of the dispatchFetch method: the request must be an instance of the global Request class and the response must be the instance of the global Response class. Vite will throw a TypeError if this is not the case.
Note that although the FetchableDevEnvironment is implemented as a class, it is considered an implementation detail by the Vite team and might change at any moment.
If the environment does not implement the RunnableDevEnvironment or FetchableDevEnvironment interfaces, you need to set up the communication manually.
If your code can run in the same runtime as the user modules (i.e., it does not rely on Node.js-specific APIs), you can use a virtual module. This approach eliminates the need to access the value from the code using Vite's APIs.
For example, to call transformIndexHtml on the user module, the following plugin can be used:
If your code requires Node.js APIs, you can use hot.send to communicate with the code that uses Vite's APIs from the user modules. However, be aware that this approach may not work the same way after the build process.
In the CLI, calling vite build and vite build --ssr will still build the client only and ssr only environments for backward compatibility.
When the builder option is set (even to an empty object {}, which is what vite build --app does), vite build opts in to building the entire app instead. This will become the default in a future major. In this mode, Vite creates a ViteBuilder instance (the build-time equivalent of a ViteDevServer) and uses it to build all configured environments for production. By default, environments are built in series, following the order of the environments record.
A framework or user can control how the environments are built through the builder.buildApp option. It receives the ViteBuilder instance (named builder in the example below) and is responsible for building each environment; for