0
# CSS Compilation
1

2
Core CSS compilation functionality for processing Tailwind directives and generating utility classes. The compilation system transforms CSS containing Tailwind-specific at-rules into final CSS with generated utilities.
3

4
## Capabilities
5

6
### Compile Function
7

8
Main compilation function that processes CSS with Tailwind directives and returns a build system for generating final CSS.
9

10
```typescript { .api }
11
/**
12
 * Compiles CSS containing Tailwind directives into a build system
13
 * @param css - CSS source code with Tailwind directives
14
 * @param opts - Compilation options
15
 * @returns Promise resolving to compilation result with build function
16
 */
17
function compile(
18
  css: string,
19
  opts?: CompileOptions
20
): Promise<{
21
  sources: { base: string; pattern: string; negated: boolean }[];
22
  root: Root;
23
  features: Features;
24
  build(candidates: string[]): string;
25
  buildSourceMap(): DecodedSourceMap;
26
}>;
27

28
interface CompileOptions {
29
  /** Base directory for resolving imports and modules */
30
  base?: string;
31
  /** Source file path for source map generation */
32
  from?: string;
33
  /** Polyfill configuration flags */
34
  polyfills?: Polyfills;
35
  /** Custom module loader for @plugin and @config directives */
36
  loadModule?: (
37
    id: string,
38
    base: string,
39
    resourceHint: 'plugin' | 'config'
40
  ) => Promise<{
41
    path: string;
42
    base: string;
43
    module: Plugin | Config;
44
  }>;
45
  /** Custom stylesheet loader for @import directives */
46
  loadStylesheet?: (
47
    id: string,
48
    base: string
49
  ) => Promise<{
50
    path: string;
51
    base: string;
52
    content: string;
53
  }>;
54
}
55
```
56

57
**Usage Examples:**
58

59
```typescript
60
import { compile } from "tailwindcss";
61

62
// Basic compilation
63
const css = `
64
  @theme {
65
    --color-primary: #3b82f6;
66
    --color-secondary: #10b981;
67
  }
68
  
69
  @tailwind utilities;
70
`;
71

72
const result = await compile(css);
73

74
// Generate CSS for specific candidates
75
const finalCss = result.build([
76
  "bg-primary",
77
  "text-secondary", 
78
  "hover:bg-secondary",
79
  "lg:text-xl"
80
]);
81

82
// Advanced compilation with options
83
const advancedResult = await compile(css, {
84
  base: "/project/src",
85
  from: "styles.css",
86
  polyfills: Polyfills.All,
87
  loadModule: async (id, base, hint) => {
88
    // Custom module resolution
89
    const modulePath = path.resolve(base, id);
90
    const module = await import(modulePath);
91
    return {
92
      path: modulePath,
93
      base,
94
      module: module.default,
95
    };
96
  },
97
});
98
```
99

100
### Compile AST Function
101

102
Compiles an AST directly instead of parsing CSS from a string. Useful for advanced scenarios where you need to manipulate the AST before compilation.
103

104
```typescript { .api }
105
/**
106
 * Compiles an AST directly for advanced use cases
107
 * @param input - Array of AST nodes to compile
108
 * @param opts - Compilation options
109
 * @returns Promise resolving to AST compilation result
110
 */
111
function compileAst(
112
  input: AstNode[],
113
  opts?: CompileOptions
114
): Promise<{
115
  sources: { base: string; pattern: string; negated: boolean }[];
116
  root: Root;
117
  features: Features;
118
  build(candidates: string[]): AstNode[];
119
}>;
120
```
121

122
**Usage Example:**
123

124
```typescript
125
import { compileAst, styleRule, decl } from "tailwindcss";
126

127
// Create AST manually
128
const ast = [
129
  styleRule(":root", [
130
    decl("--color-primary", "#3b82f6"),
131
  ]),
132
  // Additional nodes...
133
];
134

135
const result = await compileAst(ast);
136
const compiledAst = result.build(["bg-primary"]);
137
```
138

139
### Load Design System Function
140

141
Loads a design system without full compilation. Internal API for advanced use cases.
142

143
```typescript { .api }
144
/**
145
 * Loads a design system from CSS (internal API)
146
 * @param css - CSS source with theme definitions
147
 * @param opts - Compilation options
148
 * @returns Promise resolving to DesignSystem instance
149
 */
150
function __unstable__loadDesignSystem(css: string, opts?: CompileOptions): Promise<DesignSystem>;
151
```
152

153
## Compilation Result
154

155
### Build Function
156

157
The build function returned by `compile()` generates final CSS for the provided candidates.
158

159
```typescript { .api }
160
/**
161
 * Generates final CSS for the provided utility candidates
162
 * @param candidates - Array of utility class names to generate
163
 * @returns Generated CSS string
164
 */
165
build(candidates: string[]): string;
166
```
167

168
### Build Source Map Function
169

170
Generates source maps for the compiled CSS.
171

172
```typescript { .api }
173
/**
174
 * Generates source map for the compiled CSS
175
 * @returns Decoded source map object
176
 */
177
buildSourceMap(): DecodedSourceMap;
178
```
179

180
## Compilation Features
181

182
The compilation system detects and tracks which Tailwind features are used:
183

184
```typescript { .api }
185
enum Features {
186
  None = 0,
187
  /** @apply directive was used */
188
  AtApply = 1 << 0,
189
  /** @import directive was used */
190
  AtImport = 1 << 1,
191
  /** JavaScript plugins were loaded */
192
  JsPluginCompat = 1 << 2,
193
  /** theme() function was used */
194
  ThemeFunction = 1 << 3,
195
  /** @tailwind utilities directive was used */
196
  Utilities = 1 << 4,
197
  /** @variant directive was used */
198
  Variants = 1 << 5,
199
}
200
```
201

202
## Polyfill Configuration
203

204
Control which CSS polyfills are generated:
205

206
```typescript { .api }
207
enum Polyfills {
208
  None = 0,
209
  /** Generate @property rule fallbacks */
210
  AtProperty = 1 << 0,
211
  /** Generate color-mix() fallbacks */
212
  ColorMix = 1 << 1,
213
  /** Enable all polyfills */
214
  All = AtProperty | ColorMix,
215
}
216
```
217

218
## Root Configuration
219

220
Configure how the compilation system resolves source files:
221

222
```typescript { .api }
223
type Root =
224
  /** Unknown/auto-detected root */
225
  | null
226
  /** Explicitly no root via source(none) */
227
  | 'none'
228
  /** Explicit root pattern */
229
  | { base: string; pattern: string };
230
```
231

232
## Source Configuration
233

234
The compilation result includes information about source file patterns:
235

236
```typescript { .api }
237
interface SourcePattern {
238
  /** Base directory for the pattern */
239
  base: string;
240
  /** Glob pattern for source files */
241
  pattern: string;
242
  /** Whether this pattern is negated (excluded) */
243
  negated: boolean;
244
}
245
```
246

247
## Default Export Warning
248

249
The default export throws an error directing users to use the PostCSS plugin instead.
250

251
```typescript { .api }
252
/**
253
 * Default export that throws an error about PostCSS plugin usage
254
 * @throws Error directing users to use @tailwindcss/postcss
255
 */
256
export default function postcssPluginWarning(): never;
257
```
258

259
**Note:** This function is designed to prevent direct usage of tailwindcss as a PostCSS plugin. Use `@tailwindcss/postcss` for PostCSS integration instead.