0
# @tailwindcss/node
1

2
@tailwindcss/node provides Node.js-specific utilities and runtime functionality for Tailwind CSS v4, including compilation tools, module dependency analysis, source map handling, path normalization, and optimization utilities. It serves as the core Node.js integration layer for Tailwind CSS, enabling server-side processing of styles, hot module reloading support, and seamless integration with Node.js build tools and development workflows.
3

4
## Package Information
5

6
- **Package Name**: @tailwindcss/node
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tailwindcss/node`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  compile, 
16
  compileAst, 
17
  Instrumentation, 
18
  optimize, 
19
  normalizePath, 
20
  toSourceMap,
21
  env 
22
} from "@tailwindcss/node";
23
```
24

25
For CommonJS:
26

27
```javascript
28
const { 
29
  compile, 
30
  compileAst, 
31
  Instrumentation, 
32
  optimize, 
33
  normalizePath, 
34
  toSourceMap,
35
  env 
36
} = require("@tailwindcss/node");
37
```
38

39
Specialized imports:
40

41
```typescript
42
// Require cache management
43
import { clearRequireCache } from "@tailwindcss/node/require-cache";
44

45
// ESM cache loader (used internally by Node.js module system)
46
// Note: This is registered automatically when importing the main module
47
```
48

49
## Basic Usage
50

51
```typescript
52
import { compile, CompileOptions, optimize } from "@tailwindcss/node";
53

54
// Compile Tailwind CSS with Node.js-specific features
55
const options: CompileOptions = {
56
  base: "/path/to/project",
57
  onDependency: (path: string) => {
58
    console.log("Dependency:", path);
59
  },
60
  shouldRewriteUrls: true,
61
};
62

63
const compiler = await compile(`
64
  @tailwind base;
65
  @tailwind components; 
66
  @tailwind utilities;
67
`, options);
68

69
// Get the compiled CSS
70
const css = compiler.build();
71

72
// Optimize the CSS for production
73
const optimized = optimize(css, {
74
  minify: true,
75
  file: "styles.css"
76
});
77

78
console.log(optimized.code);
79
```
80

81
## Architecture
82

83
@tailwindcss/node is built around several key components:
84

85
- **Compilation System**: Core CSS compilation with Tailwind processing, module loading, and dependency tracking
86
- **Module Resolution**: Enhanced module resolution supporting TypeScript, ESM, and CommonJS with custom resolvers
87
- **Performance Instrumentation**: Built-in profiling and timing tools for development and debugging
88
- **CSS Optimization**: Lightning CSS-based optimization with source maps and browser compatibility
89
- **Path Normalization**: Cross-platform path handling for Windows and Unix systems
90
- **Source Map Support**: Full source map generation and manipulation with inline embedding
91
- **Hot Module Reloading**: ESM cache busting and require cache management for development workflows
92

93
## Capabilities
94

95
### CSS Compilation
96

97
Core Tailwind CSS compilation functionality with Node.js-specific module loading, dependency tracking, and file system integration.
98

99
```typescript { .api }
100
function compile(css: string, options: CompileOptions): Promise<Compiler>;
101
function compileAst(ast: AstNode[], options: CompileOptions): Promise<Compiler>;
102

103
interface CompileOptions {
104
  base: string;
105
  from?: string;
106
  onDependency: (path: string) => void;
107
  shouldRewriteUrls?: boolean;
108
  polyfills?: Polyfills;
109
  customCssResolver?: Resolver;
110
  customJsResolver?: Resolver;
111
}
112

113
type Resolver = (id: string, base: string) => Promise<string | false | undefined>;
114
```
115

116
[CSS Compilation](./compilation.md)
117

118
### Performance Instrumentation
119

120
Built-in performance monitoring and profiling tools with timer support and automatic reporting for development workflows.
121

122
```typescript { .api }
123
class Instrumentation implements Disposable {
124
  constructor(defaultFlush?: (message: string) => void);
125
  hit(label: string): void;
126
  start(label: string): void;
127
  end(label: string): void;
128
  reset(): void;
129
  report(flush?: (message: string) => void): void;
130
  [Symbol.dispose](): void;
131
}
132
```
133

134
[Performance Instrumentation](./instrumentation.md)
135

136
### CSS Optimization
137

138
Lightning CSS-based optimization with minification, nesting, media query processing, and browser compatibility transformations.
139

140
```typescript { .api }
141
function optimize(input: string, options?: OptimizeOptions): TransformResult;
142

143
interface OptimizeOptions {
144
  file?: string;
145
  minify?: boolean;
146
  map?: string;
147
}
148

149
interface TransformResult {
150
  code: string;
151
  map: string | undefined;
152
}
153
```
154

155
[CSS Optimization](./optimization.md)
156

157
### Source Map Support
158

159
Comprehensive source map generation, manipulation, and serialization with inline embedding support for debugging workflows.
160

161
```typescript { .api }
162
function toSourceMap(map: DecodedSourceMap | string): SourceMap;
163

164
interface SourceMap {
165
  readonly raw: string;
166
  readonly inline: string;
167
}
168

169
type DecodedSource = {
170
  url: string;
171
  content: string;
172
};
173

174
type DecodedSourceMap = {
175
  mappings: Array<{
176
    generatedPosition: { line: number; column: number };
177
    originalPosition?: { line: number; column: number; source: DecodedSource };
178
    name?: string;
179
  }>;
180
};
181
```
182

183
[Source Map Support](./source-maps.md)
184

185
### Path Normalization
186

187
Cross-platform path normalization utilities for consistent file path handling across Windows and Unix systems.
188

189
```typescript { .api }
190
function normalizePath(originalPath: string): string;
191
```
192

193
[Path Normalization](./path-utils.md)
194

195
### Module Dependency Analysis
196

197
Recursive module dependency analysis with support for TypeScript, ESM, and CommonJS import patterns.
198

199
```typescript { .api }
200
function getModuleDependencies(absoluteFilePath: string): Promise<string[]>;
201
```
202

203
[Module Dependencies](./module-analysis.md)
204

205
### URL Processing
206

207
CSS URL rewriting functionality for asset path management and relative URL transformation in build processes.
208

209
```typescript { .api }
210
function rewriteUrls(options: {
211
  css: string;
212
  base: string;
213
  root: string;
214
}): Promise<string>;
215
```
216

217
[URL Processing](./url-processing.md)
218

219
### Cache Management
220

221
Node.js module cache management for hot module reloading and development workflows.
222

223
```typescript { .api }
224
function clearRequireCache(files: string[]): void;
225
```
226

227
[Cache Management](./cache-management.md)
228

229
## Environment Variables
230

231
The package supports several environment configurations:
232

233
```typescript { .api }
234
const env: {
235
  readonly DEBUG: boolean;
236
};
237
```
238

239
The `DEBUG` environment variable supports various patterns:
240
- `DEBUG=true` or `DEBUG=1` - Enable debugging
241
- `DEBUG=false` or `DEBUG=0` - Disable debugging  
242
- `DEBUG=*` - Enable all debug modes
243
- `DEBUG=tailwindcss` - Enable Tailwind CSS debugging
244
- `DEBUG=-tailwindcss` - Explicitly disable Tailwind CSS debugging
245

246
## Types
247

248
Core types used throughout the package:
249

250
```typescript { .api }
251
// Re-exported from tailwindcss
252
enum Features {
253
  // CSS feature flags for compilation
254
}
255

256
interface Polyfills {
257
  // CSS polyfill configuration
258
}
259

260
// Internal types
261
interface AstNode {
262
  // AST node structure (from tailwindcss)
263
}
264

265
interface Compiler {
266
  // Compilation result with build methods
267
  build(): string;
268
  root?: { pattern: string } | 'none';
269
}
270
```