CSS Processing

Relevant source files

• packages/vite/src/node/__tests__/plugins/css.spec.ts
• packages/vite/src/node/__tests__/plugins/define.spec.ts
• packages/vite/src/node/__tests__/plugins/fixtures/sass-package-resolution/.gitignore
• packages/vite/src/node/__tests__/plugins/fixtures/sass-package-resolution/node_modules/sass-pkg-with-index/index.scss
• packages/vite/src/node/__tests__/plugins/fixtures/sass-package-resolution/node_modules/sass-pkg-with-index/main.scss
• packages/vite/src/node/__tests__/plugins/fixtures/sass-package-resolution/node_modules/sass-pkg-with-index/package.json
• packages/vite/src/node/plugins/asset.ts
• packages/vite/src/node/plugins/css.ts
• packages/vite/src/node/plugins/define.ts
• packages/vite/src/node/plugins/html.ts
• packages/vite/src/node/plugins/importAnalysis.ts
• packages/vite/src/node/plugins/importAnalysisBuild.ts
• packages/vite/src/node/plugins/worker.ts
• packages/vite/src/node/server/middlewares/indexHtml.ts
• playground/css-codesplit/__tests__/css-codesplit.spec.ts
• playground/css-codesplit/async-js.css
• playground/css-codesplit/async-js.js
• playground/css-codesplit/index.html
• playground/css-codesplit/main.js
• playground/css-no-codesplit/__tests__/css-no-codesplit.spec.ts
• playground/css-no-codesplit/async-js.css
• playground/css-no-codesplit/async-js.js
• playground/css-no-codesplit/index.html
• playground/css-no-codesplit/index.js
• playground/css-sourcemap/__tests__/css-sourcemap.spec.ts
• playground/css-sourcemap/imported-nested.sass
• playground/css-sourcemap/imported.sass
• playground/css/__tests__/css.spec.ts
• playground/css/index.html
• playground/css/main.js
• playground/css/nested/_index.scss
• playground/css/postcss.config.js
• playground/css/sass.scss
• playground/css/scss-dir/main.scss
• playground/css/scss-proxy-dep/index.scss
• playground/css/vite.config.js
• playground/css/weapp.wxss
• playground/js-sourcemap/__tests__/js-sourcemap.spec.ts

This document describes how Vite processes CSS files during development and production builds, including transformation, module handling, preprocessor integration, and code splitting strategies.

For HTML-specific CSS injection, see 8.4 HTML Transformation For general asset handling, see 8.2 Asset Handling and Optimization

Overview

Vite's CSS processing system handles CSS files through a multi-stage pipeline that differs between development and production modes. In development, CSS is injected dynamically via JavaScript modules with HMR support. In production, CSS is extracted into separate files with optimization and code splitting applied.

The system supports:

• Plain CSS files
• CSS Modules with scoped class names
• Preprocessors (Sass, Less, Stylus)
• PostCSS transformations
• Lightning CSS (experimental)
• CSS code splitting per chunk
• URL resolution and asset handling
• Source map generation

Sources: packages/vite/src/node/plugins/css.ts114-165 packages/vite/src/node/plugins/css.ts227-234

CSS Processing Architecture

CSS Processing Flow

CSS processing operates through two main plugins: cssPlugin (defined at packages/vite/src/node/plugins/css.ts295) and cssPostPlugin (defined at packages/vite/src/node/plugins/css.ts457). The cssPlugin handles transformation via compileCSS(), while cssPostPlugin handles dev injection and build extraction.

Sources: packages/vite/src/node/plugins/css.ts295-452 packages/vite/src/node/plugins/css.ts457-1088 packages/vite/src/node/plugins/css.ts1192-1580

Configuration Options

CSS processing is configured via the css option defined in the CSSOptions interface:

Option	Type	Default	Description
transformer	'postcss' | 'lightningcss'	'postcss'	CSS transformer engine
modules	CSSModulesOptions | false	undefined	CSS Modules configuration
preprocessorOptions	object	{}	Options for scss, sass, less, styl, stylus
preprocessorMaxWorkers	number | true	true	Run preprocessors in workers pool
postcss	string | object	Auto-detected	PostCSS config path or options
devSourcemap	boolean	false	Enable CSS sourcemaps in dev
lightningcss	LightningCSSOptions	undefined	Lightning CSS options

The default configurations are defined in cssConfigDefaults packages/vite/src/node/plugins/css.ts195-207

Sources: packages/vite/src/node/plugins/css.ts113-164 packages/vite/src/node/plugins/css.ts195-207

CSS Plugin (vite:css)

CSS Plugin Core Functions

The cssPlugin() function at packages/vite/src/node/plugins/css.ts295 creates the main CSS transformation plugin. It uses filter objects with CSS_LANGS_RE pattern to match CSS file requests.

Key Responsibilities:

• Intercepts CSS file loads with special query handling (?url, ?inline) packages/vite/src/node/plugins/css.ts337-363
• Invokes compileCSS() for transformation at packages/vite/src/node/plugins/css.ts1192
• Manages cssModulesCache WeakMap at packages/vite/src/node/plugins/css.ts268
• Creates preprocessorWorkerController in buildStart at packages/vite/src/node/plugins/css.ts324-330

Load Hook Behavior:

• Filter: { id: CSS_LANGS_RE } at packages/vite/src/node/plugins/css.ts338-340
• Checks urlRE.test(id) for ?url query at packages/vite/src/node/plugins/css.ts342
• Throws error if isModuleCSSRequest(id) with ?url at packages/vite/src/node/plugins/css.ts343-348

Transform Hook Behavior:

• Filter: { id: { include: CSS_LANGS_RE, exclude: [commonjsProxyRE, SPECIAL_QUERY_RE] } } at packages/vite/src/node/plugins/css.ts366-370
• Creates urlResolver callback that calls idResolver(environment, url, importer) at packages/vite/src/node/plugins/css.ts374-421
• Calls compileCSS() with environment and URL resolver at packages/vite/src/node/plugins/css.ts423-434
• Stores CSS Modules in cache: moduleCache.set(id, modules) at packages/vite/src/node/plugins/css.ts435-437

Sources: packages/vite/src/node/plugins/css.ts295-452 packages/vite/src/node/plugins/css.ts337-449

CSS Compilation Pipeline

CSS Compilation Process

The compileCSS() function at packages/vite/src/node/plugins/css.ts1192 orchestrates the complete transformation pipeline.

Preprocessing Phase:

• Checks via isPreprocessorRequest(id) at packages/vite/src/node/plugins/css.ts1222
• Calls preprocessCSS() at packages/vite/src/node/plugins/css.ts2054 with worker pool if enabled.
• Handles additionalData string or function at packages/vite/src/node/plugins/css.ts2089-2113

Transformation Phase:

• Checks config.css.transformer === 'lightningcss' at packages/vite/src/node/plugins/css.ts1246
• PostCSS path: doPostCSSTransform() at packages/vite/src/node/plugins/css.ts1636 loads config via resolvePostcssConfig().
• Lightning CSS path: doLightningCSSTransform() at packages/vite/src/node/plugins/css.ts1818 uses bundleAsync().

URL Resolution:

• Calls rewriteCssUrls(postcssResult.css, replacer) at packages/vite/src/node/plugins/css.ts1282-1395
• The replacer function uses urlResolver(url, importer) callback at packages/vite/src/node/plugins/css.ts1286
• Internally calls fileToUrl(this, resolved) to get Vite URL at packages/vite/src/node/plugins/asset.ts222

Sources: packages/vite/src/node/plugins/css.ts1192-1580 packages/vite/src/node/plugins/css.ts1636-1816 packages/vite/src/node/plugins/asset.ts222

CSS Post Plugin (vite:css-post)

The cssPostPlugin() function at packages/vite/src/node/plugins/css.ts457 handles CSS output differently between development and build modes.

Development Mode Behavior:

• Direct CSS requests: isDirectCSSRequest(id) returns null at packages/vite/src/node/plugins/css.ts577-579
• Inline CSS: inlineRE.test(id) exports string at packages/vite/src/node/plugins/css.ts580-582
• Client environment: Generates calls to updateStyle helper for HMR support packages/vite/src/node/plugins/css.ts587-601

Build Mode Behavior:

• Stores styles in a internal map: styles.set(id, css) at packages/vite/src/node/plugins/css.ts608
• CSS Modules: Exports via dataToEsm(modules, ...) at packages/vite/src/node/plugins/css.ts556-559
• Plain CSS: Returns empty string to avoid JS bloat, relying on the styles map for extraction packages/vite/src/node/plugins/css.ts630

Sources: packages/vite/src/node/plugins/css.ts457-1088 packages/vite/src/node/plugins/css.ts520-632

CSS Modules

CSS Modules are detected via cssModuleRE regex at packages/vite/src/node/plugins/css.ts227

Configuration Options (CSSModulesOptions interface at packages/vite/src/node/plugins/css.ts167-193):

• scopeBehaviour: Scoping behavior ('global' or 'local').
• generateScopedName: Format or function for scoped names.
• localsConvention: Convention for exporting class names to JS.

Implementation:

• Uses postcss-modules plugin at packages/vite/src/node/plugins/css.ts1734-1816
• In build: Exports via dataToEsm(modules, ...) at packages/vite/src/node/plugins/css.ts556-559

Sources: packages/vite/src/node/plugins/css.ts167-193 packages/vite/src/node/plugins/css.ts227 packages/vite/src/node/plugins/css.ts1734-1816

Preprocessors

Vite supports Sass, Less, and Stylus preprocessors.

Worker Pool Processing: When css.preprocessorMaxWorkers is enabled (default: true packages/vite/src/node/plugins/css.ts200), preprocessors run in worker threads using WorkerWithFallback packages/vite/src/node/plugins/css.ts25

Implementation Details:

• preprocessCSS() at packages/vite/src/node/plugins/css.ts2054 dispatches to specific preprocessor logic.
• Sass resolution includes nodeResolveWithVite at packages/vite/src/node/plugins/css.ts2167

Sources: packages/vite/src/node/plugins/css.ts2054-2591 packages/vite/src/node/plugins/css.ts25

PostCSS and Lightning CSS

PostCSS Processing Uses postcss-load-config packages/vite/src/node/plugins/css.ts5 to resolve user configuration. Transformation is performed in doPostCSSTransform() packages/vite/src/node/plugins/css.ts1636

Lightning CSS (Experimental) Lightning CSS is a high-performance transformer engine. Integration is handled in doLightningCSSTransform() packages/vite/src/node/plugins/css.ts1818 which handles bundling, minification, and CSS modules.

Sources: packages/vite/src/node/plugins/css.ts1636-1816 packages/vite/src/node/plugins/css.ts1818-2052

CSS Code Splitting

Vite supports CSS output strategies controlled by build.cssCodeSplit.

Pure CSS Chunk Optimization: Chunks containing only CSS (no JS exports) are tracked and optimized.

• Detects via isPureCssChunk(chunk) packages/vite/src/node/plugins/css.ts1052
• Uses getEmptyChunkReplacer() for format-specific cleanup packages/vite/src/node/plugins/css.ts1017-1075
• Tracked in removedPureCssFilesCache packages/vite/src/node/plugins/importAnalysisBuild.ts15

Sources: packages/vite/src/node/plugins/css.ts635-940 packages/vite/src/node/plugins/css.ts1017-1075 packages/vite/src/node/plugins/importAnalysisBuild.ts15

URL Resolution and @import Inlining

URL Resolution: Vite resolves URLs in CSS files through rewriteCssUrls() packages/vite/src/node/plugins/css.ts1282

• Extracts url() patterns via cssUrlRE packages/vite/src/node/plugins/css.ts1587-1594
• Handles image-set() and -webkit-image-set().

@import Inlining: Vite inlines CSS @import statements during build to reduce requests.

• Handled via hoistAtRules() at packages/vite/src/node/plugins/css.ts1582 to ensure correct CSS order.

Sources: packages/vite/src/node/plugins/css.ts1282 packages/vite/src/node/plugins/css.ts1582-1634