0
# Source Code Transformers
1

2
Source code transformers process source code to enable advanced UnoCSS features and syntax. They analyze and transform code before CSS generation, enabling features like CSS directives, variant groups, and specialized syntax patterns.
3

4
## Capabilities
5

6
### Directives Transformer
7

8
Enables CSS directives like @apply, @screen, and @theme in CSS files.
9

10
```typescript { .api }
11
/**
12
 * CSS directives transformer for @apply, @screen, @theme directives
13
 * @param options - Configuration options
14
 * @returns Source code transformer
15
 */
16
function transformerDirectives(options?: TransformerDirectivesOptions): SourceCodeTransformer;
17

18
interface TransformerDirectivesOptions {
19
  /** Enable @apply directive */
20
  applyVariable?: string[];
21
  /** Custom CSS directives */
22
  customDirectives?: Record<string, (utils: any) => string>;
23
  /** Enable @screen directive */
24
  screen?: boolean;
25
  /** Enable @theme directive */
26
  theme?: boolean;
27
  /** Enforce theme function usage */
28
  enforceVarType?: boolean;
29
  /** Variables to throw warnings for */
30
  throwOnMissing?: boolean;
31
}
32
```
33

34
**Usage Examples:**
35

36
```typescript
37
import { defineConfig, transformerDirectives } from "unocss";
38

39
export default defineConfig({
40
  transformers: [
41
    transformerDirectives({
42
      applyVariable: ['--at-apply', '--uno-apply', '--uno'],
43
      screen: true,
44
      theme: true
45
    })
46
  ]
47
});
48
```
49

50
```css
51
/* Input CSS with directives */
52
.btn {
53
  @apply py-2 px-4 font-semibold rounded-lg shadow-md;
54
}
55

56
.container {
57
  @screen sm {
58
    max-width: 640px;
59
  }
60
}
61

62
.text-primary {
63
  color: theme('colors.blue.500');
64
}
65
```
66

67
### Variant Group Transformer
68

69
Enables variant group syntax for grouping utilities with common variants.
70

71
```typescript { .api }
72
/**
73
 * Variant group transformer for hover:(bg-red text-white) syntax
74
 * @param options - Configuration options
75
 * @returns Source code transformer
76
 */
77
function transformerVariantGroup(options?: TransformerVariantGroupOptions): SourceCodeTransformer;
78

79
interface TransformerVariantGroupOptions {
80
  /** Separators for variant groups */
81
  separators?: string[];
82
  /** Maximum parsing depth */
83
  depth?: number;
84
  /** Transform only specific files */
85
  include?: string | RegExp | (string | RegExp)[];
86
  /** Exclude specific files */
87
  exclude?: string | RegExp | (string | RegExp)[];
88
}
89
```
90

91
**Usage Examples:**
92

93
```typescript
94
import { defineConfig, transformerVariantGroup } from "unocss";
95

96
export default defineConfig({
97
  transformers: [
98
    transformerVariantGroup({
99
      separators: [':', '-'],
100
      depth: 5
101
    })
102
  ]
103
});
104
```
105

106
```html
107
<!-- Input HTML with variant groups -->
108
<div class="hover:(bg-blue-500 text-white) focus:(ring-2 ring-blue-300)">
109
  Hover and focus effects
110
</div>
111

112
<!-- Transforms to -->
113
<div class="hover:bg-blue-500 hover:text-white focus:ring-2 focus:ring-blue-300">
114
  Hover and focus effects
115
</div>
116
```
117

118
### Attributify JSX Transformer
119

120
Enables attributify mode in JSX/TSX files.
121

122
```typescript { .api }
123
/**
124
 * Attributify JSX transformer for React/Vue JSX
125
 * @param options - Configuration options
126
 * @returns Source code transformer
127
 */
128
function transformerAttributifyJsx(options?: AttributifyJsxOptions): SourceCodeTransformer;
129

130
interface AttributifyJsxOptions {
131
  /** Blocklist of attributes to ignore */
132
  blocklist?: (string | RegExp)[];
133
  /** Include only specific attributes */
134
  include?: (string | RegExp)[];
135
  /** Enable for specific frameworks */
136
  frameworks?: ('react' | 'vue' | 'svelte')[];
137
}
138
```
139

140
**Usage Examples:**
141

142
```typescript
143
import { defineConfig, transformerAttributifyJsx } from "unocss";
144

145
export default defineConfig({
146
  transformers: [
147
    transformerAttributifyJsx({
148
      frameworks: ['react', 'vue']
149
    })
150
  ]
151
});
152
```
153

154
```jsx
155
// Input JSX with attributify syntax
156
function Button() {
157
  return (
158
    <button
159
      bg="blue-500 hover:blue-600"
160
      text="white"
161
      p="x-4 y-2"
162
      rounded="md"
163
    >
164
      Click me
165
    </button>
166
  );
167
}
168
```
169

170
### Compile Class Transformer
171

172
Compiles utility classes at build time for performance optimization.
173

174
```typescript { .api }
175
/**
176
 * Class compilation transformer for build-time optimization
177
 * @param options - Configuration options
178
 * @returns Source code transformer
179
 */
180
function transformerCompileClass(options?: CompileClassOptions): SourceCodeTransformer;
181

182
interface CompileClassOptions {
183
  /** Class compilation trigger */
184
  trigger?: string | RegExp;
185
  /** Prefix for compiled classes */
186
  classPrefix?: string;
187
  /** Enable hash generation */
188
  hashFn?: (str: string) => string;
189
  /** Keep original classes */
190
  keepOriginal?: boolean;
191
}
192
```
193

194
**Usage Examples:**
195

196
```typescript
197
import { defineConfig, transformerCompileClass } from "unocss";
198

199
export default defineConfig({
200
  transformers: [
201
    transformerCompileClass({
202
      trigger: ':uno:',
203
      classPrefix: 'uno-'
204
    })
205
  ]
206
});
207
```
208

209
```html
210
<!-- Input HTML with compile trigger -->
211
<div class=":uno: text-center py-4 px-8 bg-blue-500 text-white rounded-lg shadow-md">
212
  Compiled utilities
213
</div>
214

215
<!-- Transforms to optimized single class -->
216
<div class="uno-abc123">
217
  Compiled utilities
218
</div>
219
```
220

221
## Transformer Interface
222

223
### SourceCodeTransformer Interface
224

225
```typescript { .api }
226
interface SourceCodeTransformer {
227
  /** Transformer name */
228
  name: string;
229
  /** Enforce transformer order */
230
  enforce?: 'pre' | 'post';
231
  /** Transform function */
232
  transform: (
233
    code: string,
234
    id: string,
235
    context: TransformContext
236
  ) => Awaitable<string | TransformResult | void>;
237
  /** Async transform function */
238
  transformAsync?: (
239
    code: string,
240
    id: string,
241
    context: TransformContext
242
  ) => Promise<string | TransformResult | void>;
243
}
244

245
interface TransformContext {
246
  /** UnoCSS generator instance */
247
  uno: UnoGenerator;
248
  /** Extracted tokens */
249
  tokens: Set<string>;
250
  /** Invalidate callback */
251
  invalidate?: () => void;
252
}
253

254
interface TransformResult {
255
  /** Transformed code */
256
  code: string;
257
  /** Source map */
258
  map?: any;
259
  /** Additional tokens to extract */
260
  tokens?: Set<string>;
261
}
262
```
263

264
## Multiple Transformer Usage
265

266
### Combining Transformers
267

268
```typescript
269
import { 
270
  defineConfig, 
271
  transformerDirectives, 
272
  transformerVariantGroup,
273
  transformerAttributifyJsx,
274
  transformerCompileClass
275
} from "unocss";
276

277
export default defineConfig({
278
  transformers: [
279
    // Order matters - pre-transformers first
280
    transformerVariantGroup(),
281
    transformerAttributifyJsx(),
282
    transformerDirectives(),
283
    transformerCompileClass()
284
  ]
285
});
286
```
287

288
### Framework-Specific Setups
289

290
```typescript
291
// React/Next.js setup
292
export default defineConfig({
293
  transformers: [
294
    transformerVariantGroup(),
295
    transformerAttributifyJsx({
296
      frameworks: ['react']
297
    }),
298
    transformerDirectives()
299
  ]
300
});
301

302
// Vue setup
303
export default defineConfig({
304
  transformers: [
305
    transformerVariantGroup(),
306
    transformerAttributifyJsx({
307
      frameworks: ['vue']
308
    }),
309
    transformerDirectives()
310
  ]
311
});
312

313
// CSS-only setup
314
export default defineConfig({
315
  transformers: [
316
    transformerDirectives({
317
      applyVariable: ['--uno-apply'],
318
      screen: true,
319
      theme: true
320
    })
321
  ]
322
});
323
```
324

325
## Common Use Cases
326

327
### CSS Framework Migration
328

329
```typescript
330
// Transformers for migrating from Tailwind
331
export default defineConfig({
332
  transformers: [
333
    transformerDirectives(), // @apply support
334
    transformerVariantGroup() // Variant grouping
335
  ]
336
});
337
```
338

339
### Component Library Development
340

341
```typescript
342
// Transformers for building component libraries
343
export default defineConfig({
344
  transformers: [
345
    transformerCompileClass({
346
      trigger: /uno-compile:/,
347
      keepOriginal: false
348
    }),
349
    transformerAttributifyJsx()
350
  ]
351
});
352
```
353

354
### Performance Optimization
355

356
```typescript
357
// Transformers for production optimization
358
export default defineConfig({
359
  transformers: [
360
    transformerCompileClass({
361
      trigger: ':compile:',
362
      classPrefix: 'c-'
363
    })
364
  ]
365
});
366
```