0
# Helper Functions
1

2
WindiCSS provides helper functions that enhance the developer experience with template literals, configuration utilities, and code transformation tools. These helpers simplify common workflows and improve integration with build tools.
3

4
## Capabilities
5

6
### Template Helpers
7

8
Template literal function for enhanced WindiCSS class string handling.
9

10
```typescript { .api }
11
/**
12
 * Tagged template literal for WindiCSS classes with enhanced processing
13
 * @param strings - Template literal strings
14
 * @param values - Interpolated values
15
 * @returns Processed class string
16
 */
17
function windi(strings: TemplateStringsArray, ...values: unknown[]): string;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { windi } from "windicss/helpers";
24

25
// Basic usage with template literal
26
const classes = windi`
27
  bg-blue-500 
28
  text-white 
29
  p-4 
30
  rounded-lg
31
`;
32
console.log(classes); // "bg-blue-500 text-white p-4 rounded-lg"
33

34
// With interpolated values
35
const isActive = true;
36
const size = "lg";
37

38
const buttonClasses = windi`
39
  px-4 py-2 
40
  rounded-${size}
41
  ${isActive ? 'bg-blue-500 text-white' : 'bg-gray-200 text-gray-700'}
42
  hover:opacity-90
43
  transition-opacity
44
`;
45

46
// Conditional classes
47
const cardClasses = windi`
48
  bg-white
49
  shadow-lg
50
  rounded-xl
51
  p-6
52
  ${process.env.NODE_ENV === 'development' ? 'border-2 border-red-500' : ''}
53
`;
54

55
// Dynamic values
56
const spacing = 4;
57
const color = "blue";
58
const dynamicClasses = windi`
59
  p-${spacing}
60
  bg-${color}-500
61
  text-${color === 'blue' ? 'white' : 'black'}
62
`;
63
```
64

65
### Configuration Helpers
66

67
Type-safe configuration definition helper for WindiCSS configurations.
68

69
```typescript { .api }
70
/**
71
 * Type-safe configuration definition helper
72
 * @param config - WindiCSS configuration object
73
 * @returns Same configuration with enhanced type safety
74
 */
75
function defineConfig(config: FullConfig): FullConfig;
76

77
interface FullConfig extends Config {
78
  /** Extended configuration options */
79
  [key: string]: any;
80
}
81
```
82

83
**Usage Examples:**
84

85
```typescript
86
import { defineConfig } from "windicss/helpers";
87
import type { Config } from "windicss";
88

89
// Basic configuration
90
export default defineConfig({
91
  theme: {
92
    extend: {
93
      colors: {
94
        primary: {
95
          50: '#eff6ff',
96
          500: '#3b82f6',
97
          900: '#1e3a8a'
98
        }
99
      },
100
      fontFamily: {
101
        'brand': ['Inter', 'system-ui', 'sans-serif']
102
      }
103
    }
104
  },
105
  plugins: [
106
    // plugins array
107
  ]
108
});
109

110
// Advanced configuration with full type safety
111
export default defineConfig({
112
  theme: {
113
    extend: {
114
      spacing: {
115
        '18': '4.5rem',
116
        '88': '22rem'
117
      },
118
      animation: {
119
        'fade-in': 'fadeIn 0.3s ease-in-out',
120
        'slide-up': 'slideUp 0.5s ease-out'
121
      },
122
      keyframes: {
123
        fadeIn: {
124
          '0%': { opacity: '0' },
125
          '100%': { opacity: '1' }
126
        },
127
        slideUp: {
128
          '0%': { transform: 'translateY(100%)', opacity: '0' },
129
          '100%': { transform: 'translateY(0)', opacity: '1' }
130
        }
131
      }
132
    }
133
  },
134
  shortcuts: {
135
    'btn': 'px-4 py-2 rounded-lg font-medium transition-colors',
136
    'btn-primary': 'btn bg-primary-500 text-white hover:bg-primary-600',
137
    'card': 'bg-white shadow-lg rounded-xl p-6'
138
  },
139
  plugins: [
140
    // Type-safe plugin definitions
141
  ]
142
});
143

144
// Configuration with custom properties
145
export default defineConfig({
146
  theme: {
147
    extend: {
148
      colors: {
149
        // CSS custom properties
150
        primary: 'var(--primary-color)',
151
        secondary: 'var(--secondary-color)'
152
      }
153
    }
154
  },
155
  // Custom configuration properties
156
  customOptions: {
157
    enableDebug: true,
158
    buildTarget: 'modern'
159
  }
160
} satisfies Config);
161
```
162

163
### Transform Helpers
164

165
Code transformation utilities for converting between TailwindCSS and WindiCSS imports.
166

167
```typescript { .api }
168
/**
169
 * Converts TailwindCSS imports to WindiCSS equivalents
170
 * @param code - Source code string with TailwindCSS imports
171
 * @returns Converted code with WindiCSS imports
172
 */
173
function convert(code: string): string;
174

175
/**
176
 * Transforms module imports during require/import processing
177
 * @param path - Module path to transform
178
 * @returns Transformed module or original if no transformation needed
179
 */
180
function transform(path: string): any;
181
```
182

183
**Usage Examples:**
184

185
```typescript
186
import { convert, transform } from "windicss/helpers";
187

188
// Convert TailwindCSS imports to WindiCSS
189
const tailwindCode = `
190
import { createApp } from 'vue'
191
import 'tailwindcss/tailwind.css'
192
import colors from 'tailwindcss/colors'
193
import { Config } from 'tailwindcss'
194

195
const config: Config = {
196
  theme: {
197
    extend: {
198
      colors: colors
199
    }
200
  }
201
}
202
`;
203

204
const windiCode = convert(tailwindCode);
205
console.log(windiCode);
206
// Output will have WindiCSS imports instead:
207
// import 'windicss/windi.css'
208
// import colors from 'windicss/colors'
209
// import { Config } from 'windicss'
210

211
// Transform individual imports
212
const transformedColors = transform('tailwindcss/colors');
213
// Returns windicss/colors equivalent
214

215
// Common transformation patterns
216
const transformations = [
217
  'tailwindcss/tailwind.css',    // -> 'windicss/windi.css'
218
  'tailwindcss/base.css',        // -> 'windicss/base.css'
219
  'tailwindcss/components.css',  // -> 'windicss/components.css'
220
  'tailwindcss/utilities.css',   // -> 'windicss/utilities.css'
221
  'tailwindcss/colors',          // -> 'windicss/colors'
222
  'tailwindcss/defaultTheme',    // -> 'windicss/defaultTheme'
223
  'tailwindcss/defaultConfig',   // -> 'windicss/defaultConfig'
224
  'tailwindcss/plugin',          // -> 'windicss/plugin'
225
];
226

227
transformations.forEach(path => {
228
  const transformed = transform(path);
229
  console.log(`${path} -> ${transformed}`);
230
});
231
```
232

233
### Development Helpers
234

235
Additional helpers for development and debugging workflows.
236

237
```typescript { .api }
238
/**
239
 * Console utilities for debugging and logging
240
 */
241
interface Console {
242
  log(...args: any[]): void;
243
  warn(...args: any[]): void;
244
  error(...args: any[]): void;
245
  info(...args: any[]): void;
246
}
247

248
/**
249
 * Generates autocomplete suggestions for IDE support
250
 * @param processor - WindiCSS processor instance
251
 * @returns Object with completion arrays for different utility types
252
 */
253
function generateCompletions(processor: any): {
254
  static: string[];
255
  color: string[];
256
  dynamic: string[];
257
};
258
```
259

260
**Usage Examples:**
261

262
```typescript
263
import Processor from "windicss";
264
import { generateCompletions } from "windicss/utils";
265

266
// Generate IDE completions
267
const processor = new Processor({
268
  theme: {
269
    extend: {
270
      colors: {
271
        brand: '#ff6b6b'
272
      }
273
    }
274
  }
275
});
276

277
const completions = generateCompletions(processor);
278
console.log(completions.static); // Static utility class names
279
console.log(completions.color); // Color-based utility variations
280
console.log(completions.dynamic); // Dynamic utility patterns
281

282
// Use completions for IDE integration
283
const allCompletions = [
284
  ...completions.static,
285
  ...completions.color,
286
  ...completions.dynamic
287
];
288

289
// Export completions for VS Code extension or other IDE tools
290
export { allCompletions };
291
```
292

293
### Build Integration Helpers
294

295
Helpers for integrating WindiCSS with build tools and bundlers.
296

297
```typescript { .api }
298
/**
299
 * Creates build-time processor configuration
300
 * @param options - Build options
301
 * @returns Configured processor for build tools
302
 */
303
interface BuildOptions {
304
  configPath?: string;
305
  scanPaths?: string[];
306
  exclude?: RegExp[];
307
  include?: RegExp[];
308
  minify?: boolean;
309
  preflight?: boolean;
310
}
311
```
312

313
**Usage Example:**
314

315
```typescript
316
import { defineConfig } from "windicss/helpers";
317

318
// Configuration for build tools (Vite, Webpack, etc.)
319
export default defineConfig({
320
  // Scan paths for class extraction
321
  extract: {
322
    include: [
323
      'src/**/*.{vue,html,jsx,tsx}',
324
      'pages/**/*.{vue,html,jsx,tsx}',
325
      'components/**/*.{vue,html,jsx,tsx}'
326
    ],
327
    exclude: [
328
      'node_modules',
329
      '.git',
330
      'dist'
331
    ]
332
  },
333
  
334
  // Production optimizations
335
  purge: {
336
    enabled: process.env.NODE_ENV === 'production',
337
    content: [
338
      './src/**/*.html',
339
      './src/**/*.vue',
340
      './src/**/*.jsx',
341
      './src/**/*.tsx'
342
    ]
343
  },
344
  
345
  // Build-specific options
346
  build: {
347
    minify: true,
348
    sourcemap: process.env.NODE_ENV === 'development'
349
  },
350
  
351
  theme: {
352
    extend: {
353
      // Theme configuration
354
    }
355
  }
356
});
357

358
// Framework-specific helpers
359
export const viteConfig = defineConfig({
360
  // Vite-specific WindiCSS configuration
361
  vite: {
362
    plugins: ['windicss']
363
  }
364
});
365

366
export const webpackConfig = defineConfig({
367
  // Webpack-specific WindiCSS configuration
368
  webpack: {
369
    loader: 'windicss-webpack-plugin'
370
  }
371
});
372
```
373

374
### Type Helpers
375

376
TypeScript type utilities for enhanced type safety in WindiCSS configurations.
377

378
```typescript { .api }
379
/**
380
 * Utility type for configuration with strict typing
381
 */
382
type StrictConfig<T extends Config = Config> = T & {
383
  theme: Required<T['theme']>;
384
};
385

386
/**
387
 * Helper for extracting theme types
388
 */
389
type ThemeValue<
390
  T extends Record<string, any>, 
391
  K extends keyof T
392
> = T[K];
393

394
/**
395
 * Utility for plugin configuration with options
396
 */
397
type PluginConfig<T = any> = {
398
  plugin: (options: T) => any;
399
  options: T;
400
};
401
```
402

403
**Usage Examples:**
404

405
```typescript
406
import { defineConfig } from "windicss/helpers";
407
import type { Config } from "windicss";
408

409
// Strict configuration typing
410
const strictConfig = defineConfig({
411
  theme: {
412
    colors: {
413
      primary: '#3b82f6',
414
      secondary: '#10b981'
415
    },
416
    spacing: {
417
      xs: '0.5rem',
418
      sm: '1rem'
419
    }
420
  }
421
} satisfies Config);
422

423
// Extract theme value types
424
type Colors = ThemeValue<typeof strictConfig.theme, 'colors'>;
425
type Spacing = ThemeValue<typeof strictConfig.theme, 'spacing'>;
426

427
// Plugin with typed options
428
interface TypographyOptions {
429
  className?: string;
430
  modifiers?: string[];
431
  headings?: boolean;
432
}
433

434
const typographyConfig: PluginConfig<TypographyOptions> = {
435
  plugin: (options) => {
436
    // Plugin implementation with typed options
437
    return {
438
      className: options.className || 'prose',
439
      modifiers: options.modifiers || ['sm', 'lg'],
440
      headings: options.headings ?? true
441
    };
442
  },
443
  options: {
444
    className: 'prose',
445
    modifiers: ['sm', 'lg', 'xl'],
446
    headings: true
447
  }
448
};
449
```