Windi CSS

Common errors

• Maximum call stack size exceeded at guessClassName

  cause An issue within the internal class parsing logic, especially with complex or deeply nested utility classes.
  fix Update Windi CSS to version 3.4.3 or higher, where this bug was addressed.

• Windi CSS Preflight styles not applying when using CLI

  cause A bug in the CLI integration prevented the preflight base styles from being correctly injected into the generated CSS.
  fix Upgrade Windi CSS to version 3.4.4 or newer to resolve the Preflight CLI issue.

• ClassParser incorrectly end group with jsx functional component content

  cause Parsing error when Windi CSS encountered specific patterns within JSX functional components, leading to incorrect utility class extraction.
  fix Update Windi CSS to version 3.4.3 or higher to fix the ClassParser issue with JSX content.

Warnings

• breaking Windi CSS has been officially deprecated and is no longer actively maintained. The project announced its deprecation in March 2022, recommending users migrate to Tailwind CSS v3 or newer. New features, bug fixes, and security updates are not expected.
  Fix: Migrate your project to use Tailwind CSS (v3+) and its official PostCSS setup. For existing projects, consider a migration path outlined in the Windi CSS documentation or community guides.
• gotcha While Windi CSS aimed for compatibility with Tailwind CSS v2.0 and later added some Tailwind v3 utility classes, it does not guarantee full feature parity with the latest versions of Tailwind CSS. Users might encounter missing features or subtle behavioral differences compared to official Tailwind CSS.
  Fix: Review the Windi CSS documentation for specific feature support. For full and up-to-date Tailwind CSS features, migrating to Tailwind CSS is recommended.
• gotcha Recent minor versions (v3.5.x) included fixes related to 'renamed colors' and 'default colors provided by Tailwind CSS v3'. If you rely on custom color palettes or older Tailwind v2 color names, these updates might subtly change your output without explicit configuration.
  Fix: Thoroughly test your styles after updating to v3.5.x, especially if you use default or renamed color utilities. Consult the release notes for specific color changes.
• gotcha Windi CSS is primarily designed to be integrated via bundler-specific plugins (e.g., for Vite, Webpack, Rollup, Nuxt). While a programmatic API exists, direct manual integration into a build pipeline without these plugins can be more complex and prone to misconfiguration.
  Fix: Utilize the official or community-maintained framework plugins for optimal integration and development experience. If direct API usage is necessary, consult the 'API' section of the Windi CSS documentation thoroughly.

Install

• npm install windicss npm
• yarn add windicss yarn
• pnpm add windicss pnpm

Imports

• Processor
  wrong:

  const Processor = require('windicss').Processor

  correct:

  import { Processor } from 'windicss'

  The core class for programmatic CSS processing. Windi CSS primarily ships as ESM, though CJS is available. For TypeSCript projects, this is the main entry point for compilation.
• HTMLParser
  wrong:

  const { HTMLParser } = require('windicss')

  correct:

  import { HTMLParser } from 'windicss'

  Used to parse HTML content and extract Windi CSS utility classes. Essential for the on-demand generation process.
• generate
  wrong:

  const { generate } = require('windicss')

  correct:

  import { generate } from 'windicss'

  A convenient utility function for quick generation of CSS from a string or file path, often used for simpler CLI or build steps without needing to instantiate Processor directly.

Quickstart

This quickstart demonstrates how to programmatically use Windi CSS to process HTML content, extract utility classes, and generate the corresponding CSS, including preflight styles, within a Node.js environment.

import { Processor, HTMLParser } from 'windicss';
import { readFileSync, writeFileSync } from 'fs';
import { resolve } from 'path';

async function generateWindiCSS() {
  const htmlContent = `
    <div class="p-4 bg-blue-500 text-white rounded shadow-lg">
      <h1 class="text-2xl font-bold mb-2">Hello Windi CSS!</h1>
      <p class="text-sm">This is a paragraph with some utility classes.</p>
      <button class="px-3 py-2 bg-green-500 hover:bg-green-600 rounded">Click Me</button>
    </div>
  `;

  // Initialize the Windi CSS processor
  const processor = new Processor();

  // Parse HTML to extract utility classes
  const htmlParser = new HTMLParser(htmlContent);
  const { classes } = htmlParser.parseClasses();

  // Interpret the extracted classes to generate Windi CSS utilities
  const interpreted = processor.interpret(classes.join(' '));

  // Generate the actual CSS
  const { css } = await interpreted.generate();

  // Optionally, include preflight base styles
  const preflightSheet = processor.preflight();
  const preflightCSS = preflightSheet.build();

  const finalCSS = `${preflightCSS}\n${css}`;

  const outputPath = resolve('./dist/windicss-output.css');
  writeFileSync(outputPath, finalCSS);

  console.log(`Windi CSS generated and written to ${outputPath}`);
}

generateWindiCSS().catch(console.error);