0
# Configuration
1

2
Vite's configuration system provides flexible options for customizing development and build behavior. The configuration supports TypeScript with full type safety and can be environment-specific.
3

4
## Capabilities
5

6
### Define Configuration
7

8
Creates a Vite configuration with TypeScript support and intelligent defaults.
9

10
```typescript { .api }
11
/**
12
 * Define Vite configuration with TypeScript support
13
 * @param config - Configuration object, function, or function object
14
 * @returns The same configuration with proper typing
15
 */
16
function defineConfig(config: UserConfig): UserConfig;
17
function defineConfig(configFn: UserConfigFn): UserConfigFn;
18
function defineConfig(configObj: UserConfigFnObject): UserConfigFnObject;
19

20
interface UserConfig {
21
  /** Project root directory (default: process.cwd()) */
22
  root?: string;
23
  /** Base public path (default: '/') */
24
  base?: string;
25
  /** App mode (default: 'development' for serve, 'production' for build) */
26
  mode?: string;
27
  /** Define global constants */
28
  define?: Record<string, any>;
29
  /** Plugin array */
30
  plugins?: PluginOption[];
31
  /** Server options */
32
  server?: ServerOptions;
33
  /** Build options */
34
  build?: BuildOptions;
35
  /** Preview server options */
36
  preview?: PreviewOptions;
37
  /** SSR options */
38
  ssr?: SSROptions;
39
  /** Dependency optimization options */
40
  optimizeDeps?: DepOptimizationOptions;
41
  /** Environment-specific configurations */
42
  environments?: Record<string, EnvironmentOptions>;
43
  /** Resolve options */
44
  resolve?: ResolveOptions;
45
  /** CSS options */
46
  css?: CSSOptions;
47
  /** JSON options */
48
  json?: JsonOptions;
49
  /** ESBuild options */
50
  esbuild?: ESBuildOptions;
51
  /** Worker options */
52
  worker?: WorkerOptions;
53
  /** HTML transformation options */
54
  html?: HtmlOptions;
55
  /** Asset inclusion test function */
56
  assetsInclude?: string | RegExp | (string | RegExp)[] | ((file: string) => boolean);
57
  /** Custom logger instance */
58
  customLogger?: Logger;
59
  /** Log level */
60
  logLevel?: LogLevel;
61
  /** Clear screen */
62
  clearScreen?: boolean;
63
  /** Environment files directory */
64
  envDir?: string;
65
  /** Environment variable prefix */
66
  envPrefix?: string | string[];
67
  /** App type */
68
  appType?: AppType;
69
  /** Legacy options */
70
  legacy?: LegacyOptions;
71
  /** Experimental options */
72
  experimental?: ExperimentalOptions;
73
  /** Future options */
74
  future?: FutureOptions;
75
}
76

77
type UserConfigFn = (env: ConfigEnv) => UserConfig | Promise<UserConfig>;
78
type UserConfigFnObject = { config: UserConfigFn };
79
type UserConfigExport = UserConfig | Promise<UserConfig> | UserConfigFn;
80
```
81

82
**Usage Examples:**
83

84
```typescript
85
import { defineConfig } from "vite";
86

87
// Object configuration
88
export default defineConfig({
89
  root: './src',
90
  base: '/my-app/',
91
  server: {
92
    port: 3000,
93
    open: true
94
  },
95
  build: {
96
    outDir: '../dist',
97
    sourcemap: true
98
  }
99
});
100

101
// Function configuration
102
export default defineConfig(({ command, mode }) => {
103
  const isProduction = mode === 'production';
104
  
105
  return {
106
    define: {
107
      __DEV__: !isProduction
108
    },
109
    server: {
110
      port: isProduction ? 8080 : 3000
111
    }
112
  };
113
});
114
```
115

116
### Load Configuration from File
117

118
Loads and resolves Vite configuration from the filesystem.
119

120
```typescript { .api }
121
/**
122
 * Load configuration from file
123
 * @param configEnv - Configuration environment context
124
 * @param configFile - Path to config file (optional)
125
 * @param configRoot - Config root directory (default: process.cwd())
126
 * @param logLevel - Log level for config loading
127
 * @param customLogger - Custom logger instance
128
 * @param configLoader - Config loader type ('bundle' | 'runner' | 'native', default: 'bundle')
129
 * @returns Promise resolving to config result or null
130
 */
131
function loadConfigFromFile(
132
  configEnv: ConfigEnv,
133
  configFile?: string,
134
  configRoot: string = process.cwd(),
135
  logLevel?: LogLevel,
136
  customLogger?: Logger,
137
  configLoader: 'bundle' | 'runner' | 'native' = 'bundle'
138
): Promise<{
139
  path: string;
140
  config: UserConfig;
141
  dependencies: string[];
142
} | null>;
143
```
144

145
### Resolve Configuration
146

147
Resolves the final configuration with all defaults and environment-specific values applied.
148

149
```typescript { .api }
150
/**
151
 * Resolve final configuration
152
 * @param config - Inline configuration
153
 * @param command - Command being run ('build' | 'serve')
154
 * @param defaultMode - Default mode if not specified
155
 * @returns Promise resolving to resolved configuration
156
 */
157
function resolveConfig(
158
  inlineConfig: InlineConfig,
159
  command: 'build' | 'serve',
160
  defaultMode?: string,
161
  defaultNodeEnv?: string,
162
  isPreview?: boolean
163
): Promise<ResolvedConfig>;
164

165
interface ResolvedConfig {
166
  /** Resolved root directory */
167
  root: string;
168
  /** Resolved base path */
169
  base: string;
170
  /** Resolved mode */
171
  mode: string;
172
  /** Command being executed */
173
  command: 'build' | 'serve';
174
  /** Whether in production mode */
175
  isProduction: boolean;
176
  /** Resolved plugins array */
177
  plugins: readonly Plugin[];
178
  /** Resolved server options */
179
  server: ResolvedServerOptions;
180
  /** Resolved build options */
181
  build: ResolvedBuildOptions;
182
  /** Environment variables */
183
  env: Record<string, any>;
184
  /** Logger instance */
185
  logger: Logger;
186
  /** Package.json content */
187
  packageCache: Map<string, PackageData>;
188
  /** Whether build is for SSR */
189
  isSsrBuild?: boolean;
190
  /** Public directory */
191
  publicDir: string;
192
  /** Cache directory */
193
  cacheDir: string;
194
  /** Temporary directory */
195
  tempDir: string;
196
  /** Asset file names */
197
  assetsInclude: (file: string) => boolean;
198
}
199
```
200

201
### Sort User Plugins
202

203
Sorts user plugins according to their enforcement order.
204

205
```typescript { .api }
206
/**
207
 * Sort user plugins by enforcement order
208
 * @param plugins - Array of plugin options
209
 * @returns Tuple with sorted plugin arrays [pre, normal, post]
210
 */
211
function sortUserPlugins(
212
  plugins: (Plugin | Plugin[])[] | undefined
213
): [Plugin[], Plugin[], Plugin[]];
214
```
215

216
## Configuration Types
217

218
```typescript { .api }
219
interface ConfigEnv {
220
  /** Command being executed */
221
  command: 'build' | 'serve';
222
  /** Current mode */
223
  mode: string;
224
  /** Whether this is an SSR build */
225
  isSsrBuild?: boolean;
226
  /** Whether this is preview mode */
227
  isPreview?: boolean;
228
}
229

230
interface InlineConfig extends UserConfig {
231
  /** Override config file location */
232
  configFile?: string | false;
233
}
234

235
type AppType = 'spa' | 'mpa' | 'custom';
236

237
interface EnvironmentOptions {
238
  /** Resolve options for this environment */
239
  resolve?: ResolveOptions;
240
  /** Define constants for this environment */
241
  define?: Record<string, any>;
242
}
243

244
interface DevEnvironmentOptions extends EnvironmentOptions {
245
  /** Hot update options */
246
  hot?: boolean | HmrOptions;
247
}
248

249
interface LegacyOptions {
250
  /** Support legacy browsers */
251
  buildSsrCjsExternalHeuristics?: boolean;
252
  /** Proxied FS write operations */
253
  proxiedFSWrites?: boolean;
254
}
255

256
interface ExperimentalOptions {
257
  /** Skip SSR transform */
258
  skipSsrTransform?: boolean;
259
  /** Hmr partial accept */
260
  hmrPartialAccept?: boolean;
261
}
262

263
interface FutureOptions {
264
  /** Remove export static image */
265
  removeExportStatic?: boolean;
266
}
267
```