0
# CSS Compilation
1

2
Core Tailwind CSS compilation functionality with Node.js-specific module loading, dependency tracking, and file system integration. Supports both string-based CSS and AST-based compilation with comprehensive configuration options.
3

4
## Capabilities
5

6
### Compile Function
7

8
Compiles CSS strings with Tailwind CSS processing, including dependency tracking and custom resolvers.
9

10
```typescript { .api }
11
/**
12
 * Compiles CSS with Tailwind CSS processing
13
 * @param css - CSS string to compile (typically containing @tailwind directives)
14
 * @param options - Compilation configuration options
15
 * @returns Promise resolving to a Compiler instance
16
 */
17
function compile(css: string, options: CompileOptions): Promise<Compiler>;
18

19
interface CompileOptions {
20
  /** Base directory for resolving relative paths */
21
  base: string;
22
  /** Source file path for better error reporting */
23
  from?: string;
24
  /** Callback invoked for each discovered dependency */
25
  onDependency: (path: string) => void;
26
  /** Whether to rewrite relative URLs in CSS */
27
  shouldRewriteUrls?: boolean;
28
  /** CSS polyfill configuration */
29
  polyfills?: Polyfills;
30
  /** Custom resolver for CSS imports */
31
  customCssResolver?: Resolver;
32
  /** Custom resolver for JavaScript/TypeScript modules */
33
  customJsResolver?: Resolver;
34
}
35

36
interface Compiler {
37
  /** Generates the final CSS output */
38
  build(): string;
39
  /** Source detection configuration (if any) */
40
  root?: { pattern: string } | 'none';
41
}
42
```
43

44
**Usage Examples:**
45

46
```typescript
47
import { compile, CompileOptions } from "@tailwindcss/node";
48

49
// Basic compilation
50
const compiler = await compile(`
51
  @tailwind base;
52
  @tailwind components;
53
  @tailwind utilities;
54
`, {
55
  base: process.cwd(),
56
  onDependency: (path) => console.log("Dependency:", path)
57
});
58

59
const css = compiler.build();
60

61
// Advanced compilation with custom resolvers
62
const advancedCompiler = await compile(`
63
  @import "./components.css";
64
  @tailwind utilities;
65
`, {
66
  base: "/path/to/project",
67
  from: "/path/to/project/src/styles.css",
68
  onDependency: (path) => {
69
    // Track dependencies for hot reloading
70
    watchedFiles.add(path);
71
  },
72
  shouldRewriteUrls: true,
73
  customCssResolver: async (id, base) => {
74
    // Custom CSS resolution logic
75
    if (id.startsWith("@/")) {
76
      return path.resolve(base, "src", id.slice(2));
77
    }
78
    return undefined;
79
  }
80
});
81
```
82

83
### Compile AST Function
84

85
Compiles pre-parsed AST nodes directly, useful for advanced use cases where CSS has already been parsed.
86

87
```typescript { .api }
88
/**
89
 * Compiles AST nodes with Tailwind CSS processing
90
 * @param ast - Array of parsed AST nodes
91
 * @param options - Compilation configuration options
92
 * @returns Promise resolving to a Compiler instance
93
 */
94
function compileAst(ast: AstNode[], options: CompileOptions): Promise<Compiler>;
95

96
interface AstNode {
97
  // AST node structure (implementation details from tailwindcss package)
98
}
99
```
100

101
### Load Module Function
102

103
Loads JavaScript/TypeScript modules with dependency tracking and custom resolution.
104

105
```typescript { .api }
106
/**
107
 * Loads a JavaScript/TypeScript module with dependency tracking
108
 * @param id - Module identifier (relative or package name)
109
 * @param base - Base directory for resolution
110
 * @param onDependency - Callback for each discovered dependency
111
 * @param customJsResolver - Optional custom module resolver
112
 * @returns Promise resolving to module information
113
 */
114
function loadModule(
115
  id: string,
116
  base: string,
117
  onDependency: (path: string) => void,
118
  customJsResolver?: Resolver
119
): Promise<ModuleResult>;
120

121
interface ModuleResult {
122
  /** Absolute path to the loaded module */
123
  path: string;
124
  /** Directory containing the module */
125
  base: string;
126
  /** The loaded module's exports */
127
  module: any;
128
}
129
```
130

131
**Usage Examples:**
132

133
```typescript
134
import { loadModule } from "@tailwindcss/node";
135

136
// Load a config file
137
const configModule = await loadModule(
138
  "./tailwind.config.js",
139
  process.cwd(),
140
  (path) => console.log("Config dependency:", path)
141
);
142

143
const config = configModule.module;
144

145
// Load with custom resolver
146
const themeModule = await loadModule(
147
  "@/theme",
148
  "/path/to/project",
149
  (path) => dependencies.add(path),
150
  async (id, base) => {
151
    if (id.startsWith("@/")) {
152
      return path.resolve(base, "src", id.slice(2));
153
    }
154
    return undefined;
155
  }
156
);
157
```
158

159
### Unstable Design System Loader
160

161
Loads design system configuration (experimental API subject to change).
162

163
```typescript { .api }
164
/**
165
 * Loads design system configuration (unstable API)
166
 * @param css - CSS containing design system definitions
167
 * @param options - Configuration with base directory
168
 * @returns Promise resolving to design system configuration
169
 */
170
function __unstable__loadDesignSystem(
171
  css: string, 
172
  options: { base: string }
173
): Promise<DesignSystem>;
174

175
interface DesignSystem {
176
  // Design system structure (implementation details may change)
177
}
178
```
179

180
### Resolver Type
181

182
Custom resolver function type for module and CSS resolution.
183

184
```typescript { .api }
185
/**
186
 * Custom resolver function for modules or CSS files
187
 * @param id - The identifier to resolve
188
 * @param base - Base directory for resolution
189
 * @returns Promise resolving to resolved path, false if not found, or undefined to defer to default resolver
190
 */
191
type Resolver = (id: string, base: string) => Promise<string | false | undefined>;
192
```
193

194
## Re-exported Types
195

196
The compilation module re-exports key types from the core Tailwind CSS package:
197

198
```typescript { .api }
199
/** CSS feature flags for compilation control */
200
enum Features {
201
  // Specific feature values are defined in the tailwindcss package
202
}
203

204
/** CSS polyfill configuration options */
205
interface Polyfills {
206
  // Polyfill options are defined in the tailwindcss package
207
}
208
```
209

210
## Global Hooks
211

212
The package supports global hooks for custom environments (e.g. bundlers, test frameworks):
213

214
```typescript { .api }
215
// Global functions that can be defined to customize behavior
216
declare global {
217
  var __tw_readFile: ((path: string, encoding: string) => Promise<string | null>) | undefined;
218
  var __tw_load: ((path: string) => Promise<any | null>) | undefined;
219
  var __tw_resolve: ((id: string, base: string) => string | null) | undefined;
220
}
221
```
222

223
These globals allow build tools and frameworks to provide custom implementations for file reading, module loading, and resolution.