0
# CSS Processing
1

2
Vite provides comprehensive CSS processing with support for preprocessors (Sass, Less, Stylus), CSS modules, PostCSS, and advanced optimizations. It includes source map generation, automatic vendor prefixing, and production minification.
3

4
## Capabilities
5

6
### CSS Preprocessing
7

8
Process CSS with various preprocessors and generate source maps.
9

10
```typescript { .api }
11
/**
12
 * Preprocess CSS with configured preprocessors
13
 * @param code - CSS source code
14
 * @param filename - Source filename
15
 * @param config - Resolved Vite configuration
16
 * @returns Promise resolving to preprocessing result
17
 */
18
function preprocessCSS(
19
  code: string,
20
  filename: string,
21
  config: ResolvedConfig
22
): Promise<PreprocessCSSResult>;
23

24
interface PreprocessCSSResult {
25
  /** Processed CSS code */
26
  code: string;
27
  /** Source map */
28
  map?: SourceMap;
29
  /** Additional dependencies */
30
  deps?: string[];
31
  /** Modules (for CSS modules) */
32
  modules?: Record<string, string>;
33
}
34
```
35

36
**Usage Examples:**
37

38
```typescript
39
import { preprocessCSS } from "vite";
40

41
// Process Sass file
42
const result = await preprocessCSS(
43
  '@import "variables"; .btn { color: $primary; }',
44
  './src/components/Button.scss', 
45
  config
46
);
47

48
console.log(result.code); // Compiled CSS
49
console.log(result.map);  // Source map
50
console.log(result.deps); // Dependencies found during processing
51
```
52

53
### PostCSS Source Maps
54

55
Format and handle PostCSS source maps for proper debugging.
56

57
```typescript { .api }
58
/**
59
 * Format PostCSS source maps
60
 * @param rawMap - Raw source map from PostCSS
61
 * @param file - Source file path
62
 * @returns Formatted source map
63
 */
64
function formatPostcssSourceMap(
65
  rawMap: ExistingRawSourceMap,
66
  file: string
67
): SourceMap;
68
```
69

70
### CSS Options
71

72
Configure CSS processing behavior including modules, preprocessors, and PostCSS.
73

74
```typescript { .api }
75
interface CSSOptions {
76
  /** CSS modules configuration */
77
  modules?: CSSModulesOptions;
78
  /** Preprocessor options */
79
  preprocessorOptions?: {
80
    sass?: SassPreprocessorOptions;
81
    scss?: SassPreprocessorOptions;
82
    less?: LessPreprocessorOptions;
83
    stylus?: StylusPreprocessorOptions;
84
  };
85
  /** PostCSS configuration */
86
  postcss?: PostCSSOptions;
87
  /** Enable sourcemaps in dev */
88
  devSourcemap?: boolean;
89
  /** Minify CSS */
90
  minify?: boolean | 'esbuild' | 'lightningcss';
91
  /** Lightning CSS options */
92
  lightningcss?: LightningCSSOptions;
93
}
94

95
interface ResolvedCSSOptions extends CSSOptions {
96
  modules: CSSModulesOptions | false;
97
  preprocessorOptions: {
98
    sass: SassPreprocessorOptions;
99
    scss: SassPreprocessorOptions; 
100
    less: LessPreprocessorOptions;
101
    stylus: StylusPreprocessorOptions;
102
  };
103
  postcss: PostCSSOptions;
104
  devSourcemap: boolean;
105
}
106
```
107

108
### CSS Modules
109

110
Configure CSS modules for scoped styling and class name generation.
111

112
```typescript { .api }
113
interface CSSModulesOptions {
114
  /** Scoped names pattern */
115
  scopeBehaviour?: 'global' | 'local';
116
  /** Global modules pattern */
117
  globalModulePaths?: RegExp[];
118
  /** Exported globals */
119
  exportGlobals?: boolean;
120
  /** Class name generation */
121
  generateScopedName?: string | ((name: string, filename: string, css: string) => string);
122
  /** Hash prefix */
123
  hashPrefix?: string;
124
  /** Locales path */
125
  localsConvention?: 'camelCase' | 'camelCaseOnly' | 'dashes' | 'dashesOnly';
126
}
127
```
128

129
**Usage Examples:**
130

131
```typescript
132
// CSS modules configuration
133
export default defineConfig({
134
  css: {
135
    modules: {
136
      scopeBehaviour: 'local',
137
      generateScopedName: '[name]__[local]___[hash:base64:5]',
138
      localsConvention: 'camelCaseOnly'
139
    }
140
  }
141
});
142

143
// Using CSS modules
144
// styles.module.css
145
// .button-primary { color: blue; }
146

147
// Component.tsx  
148
import styles from './styles.module.css';
149
console.log(styles.buttonPrimary); // 'Button__button-primary___2h8kJ'
150
```
151

152
### Sass/SCSS Options
153

154
Configure Sass and SCSS preprocessing options.
155

156
```typescript { .api }
157
type SassPreprocessorOptions = {
158
  /** Additional data to prepend */
159
  additionalData?: string | ((source: string, filename: string) => string);
160
  /** Include paths */
161
  includePaths?: string[];
162
  /** Indented syntax (Sass) */
163
  indentedSyntax?: boolean;
164
  /** Sass implementation */
165
  implementation?: any;
166
  /** Import function */
167
  importer?: any;
168
  /** Custom functions */
169
  functions?: Record<string, any>;
170
  /** Output style */
171
  outputStyle?: 'nested' | 'expanded' | 'compact' | 'compressed';
172
  /** Source map */
173
  sourceMap?: boolean;
174
  /** Source map contents */
175
  sourceMapContents?: boolean;
176
  /** Source map embed */
177
  sourceMapEmbed?: boolean;
178
  /** Sass options (all other Sass options) */
179
  [key: string]: any;
180
};
181
```
182

183
### Less Options
184

185
Configure Less preprocessing options.
186

187
```typescript { .api }
188
type LessPreprocessorOptions = {
189
  /** Additional data to prepend */
190
  additionalData?: string | ((source: string, filename: string) => string);
191
  /** Math mode */
192
  math?: 'always' | 'strict' | 'parens-division' | 'parens' | 'strict-legacy' | number;
193
  /** Include paths */
194
  paths?: string[];
195
  /** Global variables */
196
  globalVars?: Record<string, string>;
197
  /** Modify variables */
198
  modifyVars?: Record<string, string>;
199
  /** Filename */
200
  filename?: string;
201
  /** Plugins */
202
  plugins?: any[];
203
  /** JavaScript enabled */
204
  javascriptEnabled?: boolean;
205
  /** Less options (all other Less options) */
206
  [key: string]: any;
207
};
208
```
209

210
### Stylus Options
211

212
Configure Stylus preprocessing options.
213

214
```typescript { .api }
215
type StylusPreprocessorOptions = {
216
  /** Additional data to prepend */
217
  additionalData?: string | ((source: string, filename: string) => string);
218
  /** Include paths */
219
  paths?: string[];
220
  /** Global variables */
221
  globals?: Record<string, any>;
222
  /** Define functions */
223
  functions?: Record<string, any>;
224
  /** Use plugins */
225
  use?: any[];
226
  /** Import files */
227
  imports?: string[];
228
  /** Include CSS */
229
  includeCSS?: boolean;
230
  /** Stylus options (all other Stylus options) */
231
  [key: string]: any;
232
};
233
```
234

235
### PostCSS Configuration
236

237
Configure PostCSS processing and plugins.
238

239
```typescript { .api }
240
type PostCSSOptions = {
241
  /** PostCSS plugins */
242
  plugins?: any[];
243
  /** PostCSS options */
244
  parser?: string | any;
245
  stringifier?: string | any;
246
  syntax?: string | any;
247
  map?: boolean | any;
248
  from?: string;
249
  to?: string;
250
  /** PostCSS configuration (all other PostCSS options) */
251
  [key: string]: any;
252
};
253
```
254

255
**Usage Examples:**
256

257
```typescript
258
import autoprefixer from 'autoprefixer';
259
import tailwindcss from 'tailwindcss';
260

261
export default defineConfig({
262
  css: {
263
    postcss: {
264
      plugins: [
265
        tailwindcss(),
266
        autoprefixer()
267
      ]
268
    },
269
    preprocessorOptions: {
270
      scss: {
271
        additionalData: `@import "@/styles/variables.scss";`,
272
        includePaths: ['node_modules', 'src/styles']
273
      },
274
      less: {
275
        globalVars: {
276
          'primary-color': '#1890ff',
277
          'border-radius': '4px'
278
        }
279
      }
280
    }
281
  }
282
});
283
```
284

285
## CSS Request Detection
286

287
Utilities for detecting CSS-related requests.
288

289
```typescript { .api }
290
/**
291
 * Check if request is for CSS
292
 * @param request - Request path or URL
293
 * @returns Whether request is for CSS file
294
 */
295
function isCSSRequest(request: string): boolean;
296

297
/**
298
 * Check if request is for CSS modules
299
 * @param request - Request path or URL
300
 * @returns Whether request is for CSS modules
301
 */
302
function isCSSModulesRequest(request: string): boolean;
303

304
/**
305
 * Check if request is for preprocessor file
306
 * @param request - Request path or URL
307
 * @returns Whether request is for preprocessor file (sass, less, stylus)
308
 */
309
function isPreprocessorRequest(request: string): boolean;
310
```
311

312
## CSS Asset Handling
313

314
Handle CSS assets during build and development.
315

316
```typescript { .api }
317
/**
318
 * CSS asset information
319
 */
320
interface CSSAssetInfo {
321
  /** Asset filename */
322
  filename: string;
323
  /** CSS source */
324
  source: string;
325
  /** Whether it's a CSS module */
326
  isModule: boolean;
327
}
328

329
/**
330
 * CSS chunk information
331
 */
332
interface CSSChunkInfo {
333
  /** CSS content */
334
  css: string;
335
  /** Associated JS chunks */
336
  chunks: string[];
337
  /** CSS modules mapping */
338
  modules?: Record<string, string>;
339
}
340
```
341

342
## Lightning CSS Options
343

344
Configuration for Lightning CSS (fast CSS processor).
345

346
```typescript { .api }
347
interface LightningCSSOptions {
348
  /** Minify CSS */
349
  minify?: boolean;
350
  /** Target browsers */
351
  targets?: string | string[] | Record<string, any>;
352
  /** Include features */
353
  include?: number;
354
  /** Exclude features */  
355
  exclude?: number;
356
  /** Draft features */
357
  drafts?: {
358
    nesting?: boolean;
359
    customMedia?: boolean;
360
  };
361
  /** Non-standard features */
362
  nonStandard?: {
363
    deepSelectorCombinator?: boolean;
364
  };
365
  /** Pseudo classes */
366
  pseudoClasses?: Record<string, string>;
367
  /** Unused symbols */
368
  unusedSymbols?: string[];
369
}
370
```