vite-plugin-css-export

3.1.0 verified Mon Apr 27 auth: no javascript

A Vite plugin that exports CSS variable values (defined via `:export` pseudo-class) to JavaScript, enabling sharing of design tokens between CSS/SCSS/LESS and JS. Current stable version is 3.1.0, compatible with Vite 5–8 and Node >=20.19.0 (or >=22.12.0). Key differentiators: support for nested `:export` rules that produce nested JS objects, works with CSS pre-processors (Sass, Less, Stylus) and CSS Modules, and ships TypeScript declarations. Releases follow semver; v3.0.0 dropped Vite 4 support and requires ESM.

Common errors

error Error: ERR_REQUIRE_ESM: require() of ES Module /node_modules/vite-plugin-css-export/dist/index.mjs from /project/vite.config.ts not supported. ↓

cause Using CommonJS `require()` with the ESM-only v3 package.

fix

Switch to ESM: rename file to .mts or set "type": "module" in package.json, then use import ViteCSSExportPlugin from 'vite-plugin-css-export'.

error TypeError: ViteCSSExportPlugin is not a function ↓

cause Importing the default export incorrectly (e.g., named import).

fix

Use default import: import ViteCSSExportPlugin from 'vite-plugin-css-export'.

error Module not found: Error: Can't resolve './styles.css?export' ↓

cause Forgetting the `?export` query suffix on the CSS import.

fix

Append ?export to the import path: import data from './styles.css?export'.

Warnings

breaking vite-plugin-css-export v3 drops support for Vite 4 (requires Vite >=5). ↓

fix Upgrade Vite to v5 or later, or pin to v2.x for Vite 4.

breaking vite-plugin-css-export v3 is ESM-only; CommonJS require() throws ERR_REQUIRE_ESM. ↓

fix Convert to ESM (use `import` or set `"type": "module"` in package.json).

gotcha The `:export` pseudo-class does not support `@media` or other at-rules; values are static at build time. ↓

fix Do not nest `:export` inside at-rules; use CSS custom properties evaluated at runtime if dynamic queries needed.

gotcha When using CSS Modules, the `?export` import returns only the exported data, not CSS module class names. ↓

fix Import both: import classes from './styles.module.css' and exportedData from './styles.module.css?export'.

deprecated The `sharedDataExportName` option (for CSS Modules) was renamed to `sharedData` in v3.0.0. ↓

fix Use `sharedData: 'cssExportedData'` instead of `sharedDataExportName: 'cssExportedData'`.

Install

npm install vite-plugin-css-export

yarn add vite-plugin-css-export

pnpm add vite-plugin-css-export

Imports

default (ViteCSSExportPlugin)

wrong

const ViteCSSExportPlugin = require('vite-plugin-css-export')

correct

import ViteCSSExportPlugin from 'vite-plugin-css-export'

Package is ESM-only since v3.0.0; CommonJS require will fail. Use import.

CSSExportedData type (generated)
wrong
```
import { CSSExportedData } from 'vite-plugin-css-export'
```
correct
```
import type { CSSExportedData } from 'vite-plugin-css-export'
```
CSSExportedData is a type, not a value; must use `import type` or `--isolatedModules`. Available only if you define the interface yourself; the package exports no concrete type.
CSS module export (`?export` query)
wrong
```
import cssResult from './style.css'
```
correct
```
import cssResult from './style.css?export'
```
Must append `?export` to the import path. Without it, you get the default Vite CSS module output (class name mappings).

Quickstart

Minimal Vite config with plugin, a CSS file exporting variables, and TS import using `?export` query to retrieve object.

// vite.config.ts
import ViteCSSExportPlugin from 'vite-plugin-css-export'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [ViteCSSExportPlugin()]
})

// example.css
:root { --primary: #007bff; }
:export {
  primaryColor: var(--primary);
  fontSize: 16px;
}

// main.ts (after adding reference)
/// <reference types="vite-plugin-css-export/client" />

import exported from './example.css?export'

console.log(exported.primaryColor) 'var(--primary)'
console.log(exported.fontSize) '16px'