vite-plugin-windicss

1.9.4 verified Mon Apr 27 auth: no javascript deprecated

Vite plugin for Windi CSS, a utility-first CSS framework that is fully compatible with Tailwind CSS v2 but 20-100x faster due to on-demand generation and HMR. Current stable version is 1.9.4, updated to support Vite 6. It offers attributify mode, variant groups, alias config, and design-in-devtools features. The project is actively maintained but Windi CSS is sunsetting; new projects are recommended to seek alternatives like Tailwind CSS v4 or UnoCSS. Ships TypeScript types. Peer dependency on Vite.

Common errors

error Cannot find module 'vite-plugin-windicss' or its corresponding type declarations. ↓

cause Missing type exports in older versions or incorrect import syntax.

fix

Update to v1.9.1+ and use default import: import vitePluginWindicss from 'vite-plugin-windicss'

error Error: The "path" argument must be of type string or an instance of URL. Received undefined ↓

cause Bug in v1.8.10 related to internal file resolution.

fix

Upgrade to v1.8.11 or later.

error Module not found: Can't resolve 'windicss' ↓

cause Missed installing windicss as a peer dependency.

fix

Run npm install windicss

Warnings

deprecated Windi CSS is sunsetting; consider using Tailwind CSS v4 or UnoCSS instead. ↓

fix Migrate to an alternative like UnoCSS (unocss) for similar on-demand utility-first CSS.

breaking Version 1.x requires Vite peer dependency major version matching; 1.9+ supports Vite 2-6 but not Vite 1. ↓

fix Upgrade to v1.9.4 or later to support modern Vite versions.

gotcha Do NOT use named import for the plugin: import { vitePluginWindicss } from 'vite-plugin-windicss' will fail. Use default import. ↓

fix Use import vitePluginWindicss from 'vite-plugin-windicss' (default import).

gotcha When using TypeScript, ensure 'types' are exported in package.json exports in v1.9.1+; earlier versions may have missing type declarations. ↓

fix Upgrade to v1.9.1 or later to get type declarations.

breaking Vite 4+ changed HMR handling; v1.8.9 added Vite 4 support, v1.9.3 fixed HMR for Vite 5, and v1.9.4 added Vite 6 support. Older versions may break HMR. ↓

fix Upgrade to at least v1.9.3 for Vite 5 or v1.9.4 for Vite 6.

Install

npm install vite-plugin-windicss

yarn add vite-plugin-windicss

pnpm add vite-plugin-windicss

Imports

vitePluginWindicss

wrong

import { vitePluginWindicss } from 'vite-plugin-windicss'

correct

import vitePluginWindicss from 'vite-plugin-windicss'

Default export only; named import will fail.

defineConfig
```
import { defineConfig } from 'vite-plugin-windicss'
```
Named export for configuring Windi CSS options.

WindiCssOptions

wrong

import { WindiCssOptions } from 'vite-plugin-windicss'

correct

import type { WindiCssOptions } from 'vite-plugin-windicss'

Type import only; not a runtime value.

Quickstart

Adds Windi CSS to a Vite project. Place in vite.config.ts and optionally configure via windi.config.ts.

// vite.config.ts
import { defineConfig } from 'vite'
import vitePluginWindicss from 'vite-plugin-windicss'

export default defineConfig({
  plugins: [
    vitePluginWindicss(),
  ],
})

// Optionally, create windi.config.ts
// export default { attributify: true }