0
# WindiCSS
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: windicss
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install windicss` or `pnpm add windicss`
10

11
## Core Imports
12

13
```typescript
14
import Processor from "windicss";
15
import { colors, defaultConfig, defaultTheme } from "windicss";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const Processor = require("windicss");
22
const { colors, defaultConfig, defaultTheme } = require("windicss");
23
```
24

25
Import utilities and helpers:
26

27
```typescript
28
import { windi, defineConfig } from "windicss/helpers";
29
import { toArray, hash, deepCopy } from "windicss/utils";
30
import plugin from "windicss/plugin";
31
```
32

33
Import parser system:
34

35
```typescript
36
import { HTMLParser, CSSParser, ClassParser } from "windicss/utils/parser";
37
```
38

39
Import style system:
40

41
```typescript
42
import { Property, Style, StyleSheet, Keyframes } from "windicss/utils/style";
43
```
44

45
Import built-in plugins:
46

47
```typescript
48
import aspectRatio from "windicss/plugin/aspect-ratio";
49
import filters from "windicss/plugin/filters";
50
import forms from "windicss/plugin/forms";
51
import lineClamp from "windicss/plugin/line-clamp";
52
import typography from "windicss/plugin/typography";
53
import scrollSnap from "windicss/plugin/scroll-snap";
54
```
55

56
## Basic Usage
57

58
```typescript
59
import Processor from "windicss";
60

61
// Create processor instance
62
const processor = new Processor({
63
  theme: {
64
    extend: {
65
      colors: {
66
        primary: "#3b82f6",
67
      }
68
    }
69
  }
70
});
71

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

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

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

83
## Architecture
84

85
WindiCSS is built around several key components:
86

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

96
## Capabilities
97

98
### Core Processing
99

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

102
```typescript { .api }
103
class Processor {
104
  constructor(config?: Config);
105
  extract(className: string, addComment?: boolean, prefix?: string): Style | Style[] | undefined;
106
  test(className: string, prefix?: string): boolean;
107
  interpret(classNames: string, ignoreProcessed?: boolean, handleIgnored?: Function): InterpretResult;
108
  compile(classNames: string, prefix?: string, showComment?: boolean, ignoreGenerated?: boolean, handleIgnored?: Function, outputClassName?: string): CompileResult;
109
  preflight(html?: string, includeBase?: boolean, includeGlobal?: boolean, includePlugins?: boolean, ignoreProcessed?: boolean): StyleSheet;
110
}
111

112
interface InterpretResult {
113
  success: string[];
114
  ignored: string[];
115
  styleSheet: StyleSheet;
116
}
117

118
interface CompileResult {
119
  success: string[];
120
  ignored: string[];
121
  className?: string;
122
  styleSheet: StyleSheet;
123
}
124
```
125

126
[Core Processing](./core-processing.md)
127

128
### Configuration & Theming
129

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

132
```typescript { .api }
133
interface Config {
134
  theme?: Theme;
135
  plugins?: Plugin[];
136
  presets?: Config[];
137
  variants?: Record<string, string[]>;
138
  shortcuts?: Record<string, Shortcut>;
139
  alias?: Record<string, string>;
140
  exclude?: RegExp[];
141
  important?: boolean | string;
142
  prefix?: string;
143
  separator?: string;
144
  attributify?: boolean | AttributifyOptions;
145
  preflight?: boolean | PreflightOptions;
146
  corePlugins?: string[] | Record<string, boolean>;
147
}
148

149
interface Theme {
150
  extend?: Record<string, any>;
151
  [key: string]: any;
152
}
153
```
154

155
[Configuration & Theming](./configuration.md)
156

157
### Style System
158

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

161
```typescript { .api }
162
class Style {
163
  constructor(selector?: string, property?: Property | Property[], important?: boolean);
164
  selector: string;
165
  property: Property[];
166
  meta: StyleMeta;
167
  clone(selector?: string): Style;
168
  extend(style: Style): Style;
169
  build(minify?: boolean): string;
170
}
171

172
class Property {
173
  constructor(name: string | string[], value?: string, comment?: string, important?: boolean);
174
  name: string | string[];
175
  value?: string;
176
  important: boolean;
177
}
178

179
class StyleSheet {
180
  children: Style[];
181
  add(style: Style | Style[]): StyleSheet;
182
  sort(): StyleSheet;
183
  combine(): StyleSheet;
184
  build(minify?: boolean): string;
185
}
186
```
187

188
[Style System](./style-system.md)
189

190
### Plugin System
191

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

194
```typescript { .api }
195
function plugin(handler: PluginHandler, config?: Config): PluginOutput;
196

197
plugin.withOptions<T>(
198
  pluginFunction: (options: T) => PluginHandler,
199
  configFunction?: (options: T) => Config
200
): PluginWithOptions<T>;
201

202
interface PluginUtils {
203
  addUtilities(utilities: Record<string, any>, options?: PluginUtilOptions): Style[];
204
  addComponents(components: Record<string, any>, options?: PluginUtilOptions): Style[];
205
  addBase(baseStyles: Record<string, any>): Style[];
206
  addVariant(name: string, generator: VariantGenerator): Style | Style[];
207
  addDynamic(key: string, generator: UtilityGenerator, options?: PluginUtilOptions): UtilityGenerator;
208
  theme(path: string, defaultValue?: any): any;
209
  config(path: string, defaultValue?: any): any;
210
  e(selector: string): string;
211
  prefix(selector: string): string;
212
}
213
```
214

215
[Plugin System](./plugin-system.md)
216

217
### Utility Functions
218

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

221
```typescript { .api }
222
function toArray<T>(v: T | T[]): T[];
223
function hash(str: string): string;
224
function deepCopy<T>(source: T): T;
225
function camelToDash(str: string): string;
226
function dashToCamel(str: string): string;
227
function isNumber(amount: string): boolean;
228
function isFraction(amount: string): boolean;
229
function isSize(amount: string): boolean;
230
function hex2RGB(hex: string): number[] | undefined;
231
function toRGBA(color: string): Color | undefined;
232
function negateValue(value: string): string;
233
function getNestedValue(obj: Record<string, any>, key: string): any;
234
```
235

236
[Utility Functions](./utilities.md)
237

238
### Parser System
239

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

242
```typescript { .api }
243
class HTMLParser {
244
  constructor(html: string);
245
  parseClasses(): string[];
246
  parseElements(): ParsedElement[];
247
}
248

249
class CSSParser {
250
  constructor(css: string);
251
  parse(): ParsedCSS;
252
  extractUtilities(): string[];
253
}
254

255
class ClassParser {
256
  constructor(classNames: string, separator?: string, variants?: string[]);
257
  parse(): Element[];
258
}
259
```
260

261
[Parser System](./parser-system.md)
262

263
### Helper Functions
264

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

267
```typescript { .api }
268
function windi(strings: TemplateStringsArray, ...values: any[]): string;
269
function defineConfig(config: Config): Config;
270
function convert(code: string): string;
271
function transform(path: string): any;
272
```
273

274
[Helper Functions](./helpers.md)
275

276
### Built-in Plugins
277

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

280
```typescript { .api }
281
import aspectRatio from "windicss/plugin/aspect-ratio";
282
import filters from "windicss/plugin/filters";
283
import forms from "windicss/plugin/forms";
284
import lineClamp from "windicss/plugin/line-clamp";
285
import typography from "windicss/plugin/typography";
286
import scrollSnap from "windicss/plugin/scroll-snap";
287
```
288

289
[Built-in Plugins](./built-in-plugins.md)
290

291
## Core Types
292

293
```typescript { .api }
294
type Layer = "base" | "utilities" | "components";
295

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

300
interface AttributifyOptions {
301
  prefix?: string;
302
  separator?: string;
303
  disable?: string[];
304
}
305

306
interface PreflightOptions {
307
  safelist?: string | string[];
308
  blocklist?: string | string[];
309
  alias?: Record<string, string>;
310
  enableAll?: boolean;
311
}
312

313
interface PluginUtilOptions {
314
  respectPrefix?: boolean;
315
  respectImportant?: boolean;
316
  respectSelector?: boolean;
317
  layer?: Layer;
318
  variants?: string[];
319
  order?: number;
320
  group?: string;
321
  completions?: string[];
322
}
323

324
interface StyleMeta {
325
  layer: Layer;
326
  group: string;
327
  order: number;
328
  count: number;
329
  respectSelector?: boolean;
330
  variants?: string[];
331
}
332

333
interface Color {
334
  r: number;
335
  g: number;
336
  b: number;
337
  a?: number;
338
}
339

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

344
interface VariantUtils {
345
  modifySelectors(modifier: Function): Style;
346
  atRule(name: string): Style;
347
  pseudoClass(name: string): Style;
348
  pseudoElement(name: string): Style;
349
  parent(name: string): Style;
350
  child(name: string): Style;
351
}
352

353
interface DefaultConfig extends Config {
354
  theme: DefaultTheme;
355
  presets: Config[];
356
  plugins: Plugin[];
357
  variants: Record<string, string[]>;
358
  corePlugins: string[] | Record<string, boolean>;
359
}
360

361
interface DefaultTheme {
362
  colors: Record<string, string | Record<string, string>>;
363
  spacing: Record<string, string>;
364
  fontSize: Record<string, FontSize>;
365
  fontFamily: Record<string, string[]>;
366
  screens: Record<string, string>;
367
  extend?: Partial<DefaultTheme>;
368
}
369

370
interface ProcessorCache {
371
  count: number;
372
  html: string[];
373
  attrs: string[];
374
  classes: string[];
375
  utilities: string[];
376
  variants: string[];
377
}
378

379
interface ResolvedVariants {
380
  [key: string]: () => Style;
381
}
382

383
interface Element {
384
  raw: string;
385
  start: number;
386
  end: number;
387
  variants: string[];
388
  content?: Element[] | string;
389
  func?: string;
390
  type: 'group' | 'func' | 'utility' | 'alias';
391
  important: boolean;
392
}
393

394
interface Validata extends Element {
395
  className: string;
396
  parent?: Element;
397
}
398

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

402
interface PluginOutput {
403
  handler: PluginHandler;
404
  config?: Config;
405
}
406

407
interface PluginWithOptions<T> {
408
  (options: T): PluginOutput;
409
  __isOptionsFunction: true;
410
}
411
```