postcss-windicss

🧪 Experimental.

⚠️ Using this package is discouraged as there are some limitations of PostCSS's API. Use our first-class integrations for each dedicated framework/build tool to get the best developer experience and performance. This plugin should be your last option to use Windi CSS.

Installation

Install postcss-windicss from NPM

npm i -D postcss-windicss

Create postcss.config.js under your project root.

// postcss.config.js
module.exports = {
  plugins: {
    'postcss-windicss': {
      /* Options */
    },
  },
}

Add @windicss to your main css entry:

/* main.css */
@windicss;

Create windi.config.js / windi.config.ts under your project root with the following configurations

// windi.config.js
import { defineConfig } from 'windicss/helpers'

export default defineConfig({
  extract: {
    include: ['src/**/*.{html,vue,jsx,tsx,svelte}'],
  },
  /* ... */
})

And enjoy!

Configuration

You can pass options to the plugin by

// postcss.config.js
module.exports = {
  plugins: {
    'postcss-windicss': {
      config: 'path/to/windi.config.js', // by default it will try to find it in your project root
    }
  }
}

The full configuration options can be found here

Dev / Build modes

postcss-windicss has two different modes, one for incremental dev serving and one for a one-time production build. It's based on your process.env.NODE_ENV value.

If the tool you use does not infer it to you, you can always set them explicitly by

cross-env NODE_ENV=production npm run build # production mode
cross-env NODE_ENV=development npm run build # development mode

Touch Mode

By default, this plugin "touches" your css entry by updating the file's "updated time" (utime) to trigger the hot reload without changing its content.

It should work most of the time. But for some tools, they might also compare the file's content to avoid unnecessary hot reloads. In that cases, you will need to specify touchMode to insert-comment to get proper style updates with those tools.

// postcss.config.js
module.exports = {
  plugins: {
    'postcss-windicss': {
      touchMode: 'insert-comment' // <--
    }
  }
}

Progress

Features

[x] Build
[x] Hot reload
[x] Inline class utilities
[x] Load TypeScript / ESM configure
[x] @apply @screen @variants theme()
[ ] @layer
[ ] "Design in DevTools"
[ ] Variant Groups (probably not possible)

Frameworks

Currently tested on

[x] Vite
[x] Webpack
[x] Snowpack

Feel free to add more if you got it working on other tools/frameworks!

Integrations

@leanup/stack

windicss / postcss-windicss

readme