0
# Utilities
1

2
Essential utility functions for configuration merging, logging, environment handling, and development workflows. These utilities provide the foundation for many Vite operations and are commonly used in plugins and custom tooling.
3

4
## Capabilities
5

6
### Configuration Utilities
7

8
Utilities for merging and handling Vite configurations.
9

10
```typescript { .api }
11
/**
12
 * Merge configuration objects with deep merging support
13
 * @param defaults - Default configuration object
14
 * @param overrides - Override configuration object
15
 * @param isRoot - Whether this is a root-level merge
16
 * @returns Merged configuration object
17
 */
18
function mergeConfig<T extends Record<string, any>>(
19
  defaults: T,
20
  overrides: T,
21
  isRoot?: boolean
22
): T;
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import { mergeConfig } from "vite";
29

30
// Merge configurations
31
const baseConfig = {
32
  server: {
33
    port: 3000,
34
    host: 'localhost'
35
  },
36
  build: {
37
    outDir: 'dist'
38
  }
39
};
40

41
const userConfig = {
42
  server: {
43
    port: 4000
44
  },
45
  plugins: []
46
};
47

48
const merged = mergeConfig(baseConfig, userConfig);
49
// Result: { server: { port: 4000, host: 'localhost' }, build: { outDir: 'dist' }, plugins: [] }
50
```
51

52
### Logging Utilities
53

54
Utilities for creating custom loggers and handling log output.
55

56
```typescript { .api }
57
/**
58
 * Create a custom logger instance
59
 * @param level - Log level threshold
60
 * @param options - Logger configuration options
61
 * @returns Logger instance
62
 */
63
function createLogger(level?: LogLevel, options?: LoggerOptions): Logger;
64

65
interface Logger {
66
  info(msg: string, options?: LogOptions): void;
67
  warn(msg: string, options?: LogOptions): void;
68
  error(msg: string, options?: LogOptions): void;
69
  clearScreen(type: LogType): void;
70
  hasErrorLogged(error: Error): boolean;
71
  hasWarned: boolean;
72
}
73

74
interface LoggerOptions {
75
  prefix?: string;
76
  allowClearScreen?: boolean;
77
  customLogger?: Logger;
78
}
79

80
interface LogOptions {
81
  clear?: boolean;
82
  timestamp?: boolean;
83
}
84

85
type LogLevel = 'error' | 'warn' | 'info' | 'silent';
86
type LogType = 'error' | 'warn';
87
```
88

89
**Usage Examples:**
90

91
```typescript
92
import { createLogger } from "vite";
93

94
// Create custom logger
95
const logger = createLogger('info', {
96
  prefix: '[MyPlugin]',
97
  allowClearScreen: false
98
});
99

100
logger.info('Plugin initialized');
101
logger.warn('Deprecated API usage detected');
102
logger.error('Build failed');
103
```
104

105
### Environment Utilities
106

107
Utilities for loading and processing environment variables.
108

109
```typescript { .api }
110
/**
111
 * Load environment variables from .env files
112
 * @param mode - Current mode (development, production, etc.)
113
 * @param envDir - Directory to search for .env files
114
 * @param prefixes - Environment variable prefixes to include
115
 * @returns Object with loaded environment variables
116
 */
117
function loadEnv(
118
  mode: string,
119
  envDir: string,
120
  prefixes?: string | string[]
121
): Record<string, string>;
122
```
123

124
**Usage Examples:**
125

126
```typescript
127
import { loadEnv } from "vite";
128

129
// Load environment variables
130
const env = loadEnv('development', process.cwd(), 'VITE_');
131
// Loads variables like VITE_API_URL, VITE_DEBUG, etc.
132

133
// Load with multiple prefixes
134
const allEnv = loadEnv('production', './config', ['VITE_', 'APP_']);
135
```
136

137
### Path Utilities
138

139
Utilities for path normalization and processing.
140

141
```typescript { .api }
142
/**
143
 * Normalize file paths for cross-platform compatibility
144
 * @param id - File path to normalize
145
 * @returns Normalized path with forward slashes
146
 */
147
function normalizePath(id: string): string;
148
```
149

150
**Usage Examples:**
151

152
```typescript
153
import { normalizePath } from "vite";
154

155
// Normalize paths
156
const normalized = normalizePath('src\\components\\Button.tsx');
157
// Result: 'src/components/Button.tsx'
158

159
const absoluteNormalized = normalizePath('C:\\Users\\Dev\\project\\src\\index.ts');
160
// Result: 'C:/Users/Dev/project/src/index.ts'
161
```
162

163
### Optimization Utilities
164

165
Utilities for dependency optimization and code transformation.
166

167
```typescript { .api }
168
/**
169
 * Optimize dependencies for development
170
 * @param config - Resolved Vite configuration
171
 * @param force - Force re-optimization
172
 * @param asCommand - Whether running as CLI command
173
 * @returns Promise resolving to optimization metadata
174
 */
175
function optimizeDeps(
176
  config: ResolvedConfig,
177
  force?: boolean,
178
  asCommand?: boolean
179
): Promise<DepOptimizationMetadata>;
180

181
/**
182
 * Transform code using esbuild
183
 * @param code - Source code to transform
184
 * @param filename - File name for context
185
 * @param options - Transformation options
186
 * @param inMap - Input source map
187
 * @returns Promise resolving to transformation result
188
 */
189
function transformWithEsbuild(
190
  code: string,
191
  filename: string,
192
  options?: TransformOptions,
193
  inMap?: object
194
): Promise<ESBuildTransformResult>;
195

196
interface DepOptimizationMetadata {
197
  hash: string;
198
  processing: boolean;
199
  discovered: Record<string, string>;
200
  chunks: Record<string, string>;
201
}
202

203
interface ESBuildTransformResult {
204
  code: string;
205
  map: any;
206
  warnings: any[];
207
}
208

209
interface TransformOptions {
210
  loader?: 'js' | 'jsx' | 'ts' | 'tsx';
211
  target?: string;
212
  format?: 'esm' | 'cjs' | 'iife';
213
  platform?: 'browser' | 'node' | 'neutral';
214
  define?: Record<string, string>;
215
  jsx?: 'transform' | 'preserve';
216
  jsxFactory?: string;
217
  jsxFragment?: string;
218
}
219
```
220

221
**Usage Examples:**
222

223
```typescript
224
import { optimizeDeps, transformWithEsbuild } from "vite";
225

226
// Force dependency optimization
227
await optimizeDeps(resolvedConfig, true);
228

229
// Transform TypeScript code
230
const result = await transformWithEsbuild(
231
  'const greeting: string = "Hello";',
232
  'greeting.ts',
233
  {
234
    loader: 'ts',
235
    target: 'es2020',
236
    format: 'esm'
237
  }
238
);
239

240
console.log(result.code); // Transformed JavaScript
241
```
242

243
## Import Patterns
244

245
```typescript
246
import { 
247
  mergeConfig, 
248
  createLogger, 
249
  loadEnv, 
250
  normalizePath,
251
  optimizeDeps,
252
  transformWithEsbuild
253
} from "vite";
254
```