1---
2name: vite-environment-api
3description: Vite 6+ Environment API for multiple runtime environments
4---
5 
6# Environment API (Vite 6+)
7 
8The Environment API formalizes multiple runtime environments beyond the traditional client/SSR split.
9 
10## Concept
11 
12Before Vite 6: Two implicit environments (`client` and `ssr`).
13 
14Vite 6+: Configure as many environments as needed (browser, node server, edge server, etc.).
15 
16## Basic Configuration
17 
18For SPA/MPA, nothing changes—options apply to the implicit `client` environment:
19 
20```ts
21export default defineConfig({
22  build: { sourcemap: false },
23  optimizeDeps: { include: ['lib'] },
24})
25```
26 
27## Multiple Environments
28 
29```ts
30export default defineConfig({
31  build: { sourcemap: false },  // Inherited by all environments
32  optimizeDeps: { include: ['lib'] },  // Client only
33  environments: {
34    // SSR environment
35    server: {},
36    // Edge runtime environment
37    edge: {
38      resolve: { noExternal: true },
39    },
40  },
41})
42```
43 
44Environments inherit top-level config. Some options (like `optimizeDeps`) only apply to `client` by default.
45 
46## Environment Options
47 
48```ts
49interface EnvironmentOptions {
50  define?: Record<string, any>
51  resolve?: EnvironmentResolveOptions
52  optimizeDeps: DepOptimizationOptions
53  consumer?: 'client' | 'server'
54  dev: DevOptions
55  build: BuildOptions
56}
57```
58 
59## Custom Environment Instances
60 
61Runtime providers can define custom environments:
62 
63```ts
64import { customEnvironment } from 'vite-environment-provider'
65 
66export default defineConfig({
67  environments: {
68    ssr: customEnvironment({
69      build: { outDir: '/dist/ssr' },
70    }),
71  },
72})
73```
74 
75Example: Cloudflare's Vite plugin runs code in `workerd` runtime during development.
76 
77## Backward Compatibility
78 
79- `server.moduleGraph` returns mixed client/SSR view
80- `ssrLoadModule` still works
81- Existing SSR apps work unchanged
82 
83## When to Use
84 
85- **End users**: Usually don't need to configure—frameworks handle it
86- **Plugin authors**: Use for environment-aware transformations
87- **Framework authors**: Create custom environments for their runtime needs
88 
89## Plugin Environment Access
90 
91Plugins can access environment in hooks:
92 
93```ts
94{
95  name: 'env-aware',
96  transform(code, id, options) {
97    if (options?.ssr) {
98      // SSR-specific transform
99    }
100  },
101}
102```
103 
104<!--
105Source references:
106- https://vite.dev/guide/api-environment
107- https://vite.dev/blog/announcing-vite6
108-->
109