or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

built-in-plugins.mdconfiguration.mdcore-processing.mdhelpers.mdindex.mdparser-system.mdplugin-system.mdstyle-system.mdutilities.md
tile.json

tessl/npm-windicss

Next generation utility-first CSS framework with on-demand generation and Tailwind compatibility.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/windicss@3.5.x

To install, run

npx @tessl/cli install tessl/npm-windicss@3.5.0

index.mddocs/

WindiCSS

WindiCSS is a next-generation utility-first CSS framework that provides an on-demand alternative to Tailwind CSS with faster build times and enhanced developer experience. It scans HTML and CSS to generate utilities on demand, providing faster compilation times and speedy HMR in development without requiring purging in production.

Package Information

  • Package Name: windicss
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install windicss or pnpm add windicss

Core Imports

import Processor from "windicss";
import { colors, defaultConfig, defaultTheme } from "windicss";

For CommonJS:

const Processor = require("windicss");
const { colors, defaultConfig, defaultTheme } = require("windicss");

Import utilities and helpers:

import { windi, defineConfig } from "windicss/helpers";
import { toArray, hash, deepCopy } from "windicss/utils";
import plugin from "windicss/plugin";

Import parser system:

import { HTMLParser, CSSParser, ClassParser } from "windicss/utils/parser";

Import style system:

import { Property, Style, StyleSheet, Keyframes } from "windicss/utils/style";

Import built-in plugins:

import aspectRatio from "windicss/plugin/aspect-ratio";
import filters from "windicss/plugin/filters";
import forms from "windicss/plugin/forms";
import lineClamp from "windicss/plugin/line-clamp";
import typography from "windicss/plugin/typography";
import scrollSnap from "windicss/plugin/scroll-snap";

Basic Usage

import Processor from "windicss";

// Create processor instance
const processor = new Processor({
  theme: {
    extend: {
      colors: {
        primary: "#3b82f6",
      }
    }
  }
});

// Process utility classes
const result = processor.interpret("bg-blue-500 text-white p-4 rounded-lg");
console.log(result.styleSheet.build());

// Test if class is valid
const isValid = processor.test("bg-primary");

// Extract styles for specific class
const styles = processor.extract("hover:bg-red-500");

Architecture

WindiCSS is built around several key components:

  • Processor Class: Core engine that handles CSS generation, configuration management, and utility processing with caching and optimization
  • Style System: Property, Style, Keyframes, and StyleSheet classes for CSS representation and manipulation
  • Parser System: HTMLParser, CSSParser, and ClassParser for extracting and processing content from various sources
  • Plugin System: Extensible architecture for custom utilities, components, variants, and configurations with built-in and third-party plugin support
  • Configuration System: Theme-based configuration with preset support, inheritance, and dynamic resolution
  • Variant System: Responsive, state-based, and custom variant generation with conditional styling support
  • Caching System: Intelligent caching for processed utilities, variants, and configurations to optimize performance
  • Handler System: Utility handler creation and management for dynamic utility generation

Capabilities

Core Processing

The main WindiCSS processor that handles CSS generation, configuration management, and utility processing. Essential for all WindiCSS operations.

class Processor {
  constructor(config?: Config);
  extract(className: string, addComment?: boolean, prefix?: string): Style | Style[] | undefined;
  test(className: string, prefix?: string): boolean;
  interpret(classNames: string, ignoreProcessed?: boolean, handleIgnored?: Function): InterpretResult;
  compile(classNames: string, prefix?: string, showComment?: boolean, ignoreGenerated?: boolean, handleIgnored?: Function, outputClassName?: string): CompileResult;
  preflight(html?: string, includeBase?: boolean, includeGlobal?: boolean, includePlugins?: boolean, ignoreProcessed?: boolean): StyleSheet;
}

interface InterpretResult {
  success: string[];
  ignored: string[];
  styleSheet: StyleSheet;
}

interface CompileResult {
  success: string[];
  ignored: string[];
  className?: string;
  styleSheet: StyleSheet;
}

Core Processing

Configuration & Theming

Configuration management system with theme support, preset handling, and dynamic configuration resolution.

interface Config {
  theme?: Theme;
  plugins?: Plugin[];
  presets?: Config[];
  variants?: Record<string, string[]>;
  shortcuts?: Record<string, Shortcut>;
  alias?: Record<string, string>;
  exclude?: RegExp[];
  important?: boolean | string;
  prefix?: string;
  separator?: string;
  attributify?: boolean | AttributifyOptions;
  preflight?: boolean | PreflightOptions;
  corePlugins?: string[] | Record<string, boolean>;
}

interface Theme {
  extend?: Record<string, any>;
  [key: string]: any;
}

Configuration & Theming

Style System

CSS representation classes for properties, styles, keyframes, and stylesheets with full manipulation capabilities.

class Style {
  constructor(selector?: string, property?: Property | Property[], important?: boolean);
  selector: string;
  property: Property[];
  meta: StyleMeta;
  clone(selector?: string): Style;
  extend(style: Style): Style;
  build(minify?: boolean): string;
}

class Property {
  constructor(name: string | string[], value?: string, comment?: string, important?: boolean);
  name: string | string[];
  value?: string;
  important: boolean;
}

class StyleSheet {
  children: Style[];
  add(style: Style | Style[]): StyleSheet;
  sort(): StyleSheet;
  combine(): StyleSheet;
  build(minify?: boolean): string;
}

Style System

Plugin System

Extensible plugin architecture for creating custom utilities, components, variants, and configurations.

function plugin(handler: PluginHandler, config?: Config): PluginOutput;

plugin.withOptions<T>(
  pluginFunction: (options: T) => PluginHandler,
  configFunction?: (options: T) => Config
): PluginWithOptions<T>;

interface PluginUtils {
  addUtilities(utilities: Record<string, any>, options?: PluginUtilOptions): Style[];
  addComponents(components: Record<string, any>, options?: PluginUtilOptions): Style[];
  addBase(baseStyles: Record<string, any>): Style[];
  addVariant(name: string, generator: VariantGenerator): Style | Style[];
  addDynamic(key: string, generator: UtilityGenerator, options?: PluginUtilOptions): UtilityGenerator;
  theme(path: string, defaultValue?: any): any;
  config(path: string, defaultValue?: any): any;
  e(selector: string): string;
  prefix(selector: string): string;
}

Plugin System

Utility Functions

General-purpose utility functions for common operations, type checking, color manipulation, and string processing.

function toArray<T>(v: T | T[]): T[];
function hash(str: string): string;
function deepCopy<T>(source: T): T;
function camelToDash(str: string): string;
function dashToCamel(str: string): string;
function isNumber(amount: string): boolean;
function isFraction(amount: string): boolean;
function isSize(amount: string): boolean;
function hex2RGB(hex: string): number[] | undefined;
function toRGBA(color: string): Color | undefined;
function negateValue(value: string): string;
function getNestedValue(obj: Record<string, any>, key: string): any;

Utility Functions

Parser System

HTML, CSS, and utility class parsing capabilities for extracting and processing content from various sources.

class HTMLParser {
  constructor(html: string);
  parseClasses(): string[];
  parseElements(): ParsedElement[];
}

class CSSParser {
  constructor(css: string);
  parse(): ParsedCSS;
  extractUtilities(): string[];
}

class ClassParser {
  constructor(classNames: string, separator?: string, variants?: string[]);
  parse(): Element[];
}

Parser System

Helper Functions

Template helpers, configuration utilities, and transformation functions for enhanced developer experience.

function windi(strings: TemplateStringsArray, ...values: any[]): string;
function defineConfig(config: Config): Config;
function convert(code: string): string;
function transform(path: string): any;

Helper Functions

Built-in Plugins

Official WindiCSS plugins for aspect ratio, filters, forms, line clamping, typography, and scroll snap utilities.

import aspectRatio from "windicss/plugin/aspect-ratio";
import filters from "windicss/plugin/filters";
import forms from "windicss/plugin/forms";
import lineClamp from "windicss/plugin/line-clamp";
import typography from "windicss/plugin/typography";
import scrollSnap from "windicss/plugin/scroll-snap";

Built-in Plugins

Core Types

type Layer = "base" | "utilities" | "components";

interface Shortcut {
  [key: string]: string | Record<string, any>;
}

interface AttributifyOptions {
  prefix?: string;
  separator?: string;
  disable?: string[];
}

interface PreflightOptions {
  safelist?: string | string[];
  blocklist?: string | string[];
  alias?: Record<string, string>;
  enableAll?: boolean;
}

interface PluginUtilOptions {
  respectPrefix?: boolean;
  respectImportant?: boolean;
  respectSelector?: boolean;
  layer?: Layer;
  variants?: string[];
  order?: number;
  group?: string;
  completions?: string[];
}

interface StyleMeta {
  layer: Layer;
  group: string;
  order: number;
  count: number;
  respectSelector?: boolean;
  variants?: string[];
}

interface Color {
  r: number;
  g: number;
  b: number;
  a?: number;
}

type PluginHandler = (utils: PluginUtils) => void;
type UtilityGenerator = (props: { Utility: any; Style: any; Property: any; Keyframes: any }) => Style | Style[] | undefined;
type VariantGenerator = (utils: VariantUtils) => Style;

interface VariantUtils {
  modifySelectors(modifier: Function): Style;
  atRule(name: string): Style;
  pseudoClass(name: string): Style;
  pseudoElement(name: string): Style;
  parent(name: string): Style;
  child(name: string): Style;
}

interface DefaultConfig extends Config {
  theme: DefaultTheme;
  presets: Config[];
  plugins: Plugin[];
  variants: Record<string, string[]>;
  corePlugins: string[] | Record<string, boolean>;
}

interface DefaultTheme {
  colors: Record<string, string | Record<string, string>>;
  spacing: Record<string, string>;
  fontSize: Record<string, FontSize>;
  fontFamily: Record<string, string[]>;
  screens: Record<string, string>;
  extend?: Partial<DefaultTheme>;
}

interface ProcessorCache {
  count: number;
  html: string[];
  attrs: string[];
  classes: string[];
  utilities: string[];
  variants: string[];
}

interface ResolvedVariants {
  [key: string]: () => Style;
}

interface Element {
  raw: string;
  start: number;
  end: number;
  variants: string[];
  content?: Element[] | string;
  func?: string;
  type: 'group' | 'func' | 'utility' | 'alias';
  important: boolean;
}

interface Validata extends Element {
  className: string;
  parent?: Element;
}

type Plugin = PluginOutput | PluginWithOptions<any> | PluginFunction;
type PluginFunction = (utils: PluginUtils) => void;

interface PluginOutput {
  handler: PluginHandler;
  config?: Config;
}

interface PluginWithOptions<T> {
  (options: T): PluginOutput;
  __isOptionsFunction: true;
}