Integration for webpack

Choosing the right plugin

Windi CSS Webpack Plugin is a language and framework agnostic way to implement Windi CSS in webpack apps.

First Class Framework Support

If it's below, please use the plugin specifically built for your framework.

Framework
Nuxt.jsnuxt-windicss
Sveltesvelte-windicss-preprocess
Vue CLIvue-cli-plugin-windicss
Gridsomegridsome-plugin-windicss

Second Class Framework Support

Frameworks that have been successfully setup and documented to work with Windi.

Framework
Next.jsInstall - Example
CRACOInstall - Example
StorybookInstall - Example
Umi.jsExample

Non Supported Frameworks

Frameworks which have been tested with this package and did not work.

  • ❌ Angular

Install

If you are proceeding setup with a custom webpack build, then please report any issues you find.

yarn add windicss-webpack-plugin -D 
# npm i windicss-webpack-plugin -D

If you were previously using Tailwind, please see the migration guide.

Configure webpack

You will need to add the plugin to your webpack configuration. If you have access to modify the webpack.config.js directly, then you can do the following.

// webpack.config.js
import WindiCSS from 'windicss-webpack-plugin'

export default {
  // ...
  plugins: [
    new WindiCSS(),
  ],
}

Non ES Modules Install

For webpack configurations which don't support the es module import syntax, you can try the following.

// webpack.config.js
const WindiCSS = require('windicss-webpack-plugin').default

export default {
  // ...
  plugins: [
    new WindiCSS(),
  ],
}

Include the virtual module

Within an entry point file or something only loaded once, add the import of windi.css.

// main.js
import 'windi.css'
// require('windi.css')

Windi Config

Add a file called windi.config.ts to your project root if you don't have it already.

Scanning

If you have issues when you start Windi that your classes aren't being picked up, you may need to modify the scanning.

On server start, Windi will scan your code and extract the utility usages. By default, only files under src/ with extensions "html", "vue", "md", "mdx", "pug", "jsx", "tsx", "svelte", "ts", "js", "css", "postcss" will be included.

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

export default defineConfig({
  extract: {
    // A common use case is scanning files from the root directory
    include: ['**/*.{vue,html,jsx,tsx}'],
    // if you are excluding files, make sure you always include node_modules and .git
    exclude: ['node_modules', '.git', 'dist'],
  },
})

Configuration

Preflight (style resetting)

Preflight is enabled on-demanded. If you'd like to completely disable it, you can configure it as below

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

export default defineConfig({
  preflight: false,
})

Safelist

By default, we scan your source code statically and find all the usages of the utilities then generated corresponding CSS on-demand. However, there is some limitation that utilities that decided in the runtime can not be matched efficiently, for example

<!-- will not be detected -->
<div className={`p-${size}`}>

For that, you will need to specify the possible combinations in the safelist options of windi.config.ts.

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

export default defineConfig({
  safelist: 'p-1 p-2 p-3 p-4',
})

Or you can do it this way

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

function range(size, startAt = 1) {
  return Array.from(Array(size).keys()).map(i => i + startAt)
}

export default defineConfig({
  safelist: [
    range(30).map(i => `p-${i}`), // p-1 to p-3
    range(10).map(i => `mt-${i}`), // mt-1 to mt-10
  ],
})

Layers Ordering

By default, importing windi.css or virtual:windi.css will import all the three layers with the order base - components - utilities. If you want to have better controls over the orders, you can separate them by:

- import 'virtual:windi.css'
+ import 'virtual:windi-base.css'
+ import 'virtual:windi-components.css'
+ import 'virtual:windi-utilities.css'

You can also make your custom css be able to be overridden by certain layers:

  import 'virtual:windi-base.css'
  import 'virtual:windi-components.css'
+ import './my-style.css'
  import 'virtual:windi-utilities.css'

Full Configuration

See options.ts for full configuration details.

Install Examples

Next.js

next.config.js

const WindiCSS = require('windicss-webpack-plugin').default

module.exports = {
  // ...
  webpack(config) {
    config.plugins.push(new WindiCSS())
    return config
  },
}

pages/_app.js

import 'windi.css'

windi.config.ts

import { defineConfig } from 'windicss/helpers'

export default defineConfig({
  extract: {
    include: ['**/*.{jsx,css}'],
    exclude: ['node_modules', '.git', '.next'],
  },
})

Note: JSX usage is experimental. Please report any issues you find.

Create React App - CRACO

craco.config.js

const WindiCSS = require('windicss-webpack-plugin').default

module.exports = {
  // ...
  webpack: {
    plugins: {
      add: [
        new WindiCSS({
          virtualModulePath: 'src',
        }),
      ],
    },
  },
}

src/index.js

import './virtual:windi.css'

windi.config.ts

import { defineConfig } from 'windicss/helpers'

export default defineConfig({
  extract: {
    include: ['**/*.{jsx,js,css,html}'],
    exclude: ['node_modules', '.git', '.next'],
  },
})

Note: JSX usage is experimental. Please report any issues you find.

Non ES Modules

For webpack configurations which don't support the es module import syntax, you can try the following.

// webpack.config.js
const WindiCSS = require('windicss-webpack-plugin').default

export default {
  // ...
  plugins: [
    new WindiCSS(),
  ],
}
// main.js
require('windi.css')

Storybook

.storybook/main.js

const WindiCSS = require('windicss-webpack-plugin').default

module.exports = {
  // ...
  webpackFinal: (config) => {
    config.plugins.push(new WindiCSS())
    return config
  },
}

.storybook/preview.js

import 'windi.css'

Warning: CSS pre-processors (like SCSS, LESS) will not work with @apply, use plain css.

Code Examples

See examples for sample projects.