0
# CSS Optimization
1

2
Lightning CSS-based optimization with minification, nesting, media query processing, and browser compatibility transformations. Provides comprehensive CSS optimization including source map preservation and custom media query handling.
3

4
## Capabilities
5

6
### Optimize Function
7

8
Optimizes CSS using Lightning CSS with advanced transformations and browser compatibility.
9

10
```typescript { .api }
11
/**
12
 * Optimizes CSS using Lightning CSS with custom transformations
13
 * @param input - CSS string to optimize
14
 * @param options - Optimization configuration options
15
 * @returns Optimization result with code and source map
16
 */
17
function optimize(
18
  input: string, 
19
  options?: OptimizeOptions
20
): TransformResult;
21

22
interface OptimizeOptions {
23
  /** The file being transformed (for source maps and error reporting) */
24
  file?: string;
25
  /** Enable minified output */
26
  minify?: boolean;
27
  /** Input source map string for source map chaining */
28
  map?: string;
29
}
30

31
interface TransformResult {
32
  /** Optimized CSS code */
33
  code: string;
34
  /** Output source map (undefined if no input map provided) */
35
  map: string | undefined;
36
}
37
```
38

39
**Usage Examples:**
40

41
```typescript
42
import { optimize } from "@tailwindcss/node";
43

44
// Basic optimization
45
const result = optimize(`
46
  .container {
47
    display: flex;
48
    flex-direction: column;
49
  }
50
  
51
  @media (min-width: 768px) {
52
    .container {
53
      flex-direction: row;
54
    }
55
  }
56
`);
57

58
console.log(result.code);
59

60
// Production optimization with minification
61
const minified = optimize(css, {
62
  minify: true,
63
  file: "styles.css"
64
});
65

66
console.log(minified.code); // Minified output
67
```
68

69
### Source Map Support
70

71
The optimization function supports source map chaining for debugging:
72

73
```typescript
74
import { optimize } from "@tailwindcss/node";
75

76
// With existing source map
77
const previousMap = JSON.stringify({
78
  version: 3,
79
  sources: ["input.css"],
80
  mappings: "AAAA,UAAU",
81
  // ... other source map properties
82
});
83

84
const result = optimize(css, {
85
  file: "styles.css",
86
  map: previousMap
87
});
88

89
// Result includes chained source map
90
if (result.map) {
91
  console.log("Source map preserved:", result.map);
92
}
93
```
94

95
### Advanced Configuration
96

97
The optimization process uses Lightning CSS with specific configurations:
98

99
```typescript
100
import { optimize } from "@tailwindcss/node";
101

102
// The optimize function internally uses these Lightning CSS features:
103
// - CSS Nesting support
104
// - Media Query range syntax handling  
105
// - Custom media queries (draft support)
106
// - Deep selector combinator (non-standard)
107
// - Error recovery for malformed CSS
108

109
const result = optimize(`
110
  .card {
111
    &:hover {
112
      transform: scale(1.05);
113
    }
114
    
115
    @media (width >= 768px) {
116
      padding: 2rem;
117
    }
118
  }
119
  
120
  @custom-media --desktop (min-width: 1024px);
121
  
122
  @media (--desktop) {
123
    .card {
124
      max-width: 800px;
125
    }
126
  }
127
`, {
128
  minify: true,
129
  file: "components.css"
130
});
131

132
console.log(result.code);
133
```
134

135
## Browser Compatibility
136

137
The optimization process targets specific browser versions:
138

139
```typescript
140
// Internal browser targets (for reference):
141
const targets = {
142
  safari: "16.4",      // Safari 16.4+
143
  ios_saf: "16.4",     // iOS Safari 16.4+
144
  firefox: "128",      // Firefox 128+
145
  chrome: "111"        // Chrome 111+
146
};
147
```
148

149
## CSS Features
150

151
The optimization process includes and excludes specific CSS features:
152

153
### Included Features
154
- **CSS Nesting**: Native CSS nesting syntax
155
- **Media Queries**: Including range syntax and custom media
156

157
### Excluded Features  
158
- **Logical Properties**: CSS logical properties are not transformed
159
- **Dir Selector**: Direction pseudo-classes are not processed
160
- **Light-Dark Function**: CSS light-dark() function is not processed
161

162
### Special Handling
163

164
The optimizer includes special handling for media query compatibility:
165

166
```typescript
167
// Media query range syntax is transformed for compatibility
168
// Input:  @media not (width < 768px)
169
// Output: @media not all and (width < 768px)
170

171
const result = optimize(`
172
  @media not (width < 768px) {
173
    .responsive {
174
      display: block;
175
    }
176
  }
177
`);
178
```
179

180
## Double Optimization
181

182
The function performs optimization in two passes for maximum efficiency:
183

184
```typescript
185
import { optimize } from "@tailwindcss/node";
186

187
// The optimize function internally:
188
// 1. First pass: Apply CSS nesting and basic transformations
189
// 2. Second pass: Merge adjacent rules and final optimizations
190

191
const css = `
192
  .button {
193
    padding: 0.5rem;
194
  }
195
  .button {
196
    margin: 0.25rem;
197
  }
198
`;
199

200
const result = optimize(css, { minify: true });
201
// Adjacent rules are merged: .button{padding:.5rem;margin:.25rem}
202
```
203

204
## Error Recovery
205

206
The optimization process includes error recovery for malformed CSS:
207

208
```typescript
209
import { optimize } from "@tailwindcss/node";
210

211
// Handles malformed CSS gracefully
212
const malformedCSS = `
213
  .valid { color: red; }
214
  .broken { color: ; }  /* Missing value */
215
  .also-valid { color: blue; }
216
`;
217

218
const result = optimize(malformedCSS);
219
// Valid rules are preserved, broken rules are handled gracefully
220
console.log(result.code);
221
```
222

223
## Performance Considerations
224

225
- Uses Lightning CSS for maximum performance
226
- Two-pass optimization ensures optimal output size
227
- Source maps are efficiently chained when provided
228
- Error recovery prevents optimization failures on malformed input
229
- Memory-efficient processing suitable for large CSS files