0
# Browser Targets
1

2
Browser compatibility targeting system for controlling CSS transformation, vendor prefixing, and syntax lowering based on specific browser versions and feature support.
3

4
## Capabilities
5

6
### Browserslist Integration
7

8
Convert browserslist query results into Lightning CSS targets for seamless integration with existing browser compatibility workflows.
9

10
```typescript { .api }
11
/**
12
 * Converts a browserslist result into targets that can be passed to lightningcss
13
 * @param browserslist - Array of browser version strings from browserslist
14
 * @returns Targets object for use in transformation options
15
 */
16
function browserslistToTargets(browserslist: string[]): Targets;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { browserslistToTargets, transform } from "lightningcss";
23
import browserslist from "browserslist";
24

25
// Use browserslist query
26
const browsers = browserslist('last 2 versions, not dead');
27
const targets = browserslistToTargets(browsers);
28

29
console.log(targets);
30
// Output: { chrome: 5898240, firefox: 5832704, safari: 1114112, ... }
31

32
// Use with transformation
33
const result = transform({
34
  filename: "modern.css",
35
  code: new TextEncoder().encode(`
36
    .container {
37
      display: grid;
38
      gap: 1rem;
39
      color: lab(50% 20 -30);
40
    }
41
  `),
42
  targets,
43
  minify: true
44
});
45

46
// Manual browserslist with specific queries
47
const modernTargets = browserslistToTargets(browserslist([
48
  'Chrome >= 90',
49
  'Firefox >= 88',
50
  'Safari >= 14',
51
  'Edge >= 90'
52
]));
53
```
54

55
### Direct Target Specification
56

57
Directly specify browser versions for precise control over transformation behavior.
58

59
```typescript { .api }
60
interface Targets {
61
  /** Android browser version (version * 65536) */
62
  android?: number;
63
  /** Chrome browser version (version * 65536) */
64
  chrome?: number;
65
  /** Microsoft Edge version (version * 65536) */
66
  edge?: number;
67
  /** Firefox browser version (version * 65536) */
68
  firefox?: number;
69
  /** Internet Explorer version (version * 65536) */
70
  ie?: number;
71
  /** iOS Safari version (version * 65536) */
72
  ios_saf?: number;
73
  /** Opera browser version (version * 65536) */
74
  opera?: number;
75
  /** Safari browser version (version * 65536) */
76
  safari?: number;
77
  /** Samsung Internet version (version * 65536) */
78
  samsung?: number;
79
}
80
```
81

82
**Usage Examples:**
83

84
```typescript
85
import { transform } from "lightningcss";
86

87
// Target modern browsers only
88
const modernTargets: Targets = {
89
  chrome: 90 << 16,    // Chrome 90 (90 * 65536)
90
  firefox: 88 << 16,   // Firefox 88
91
  safari: 14 << 16,    // Safari 14
92
  edge: 90 << 16       // Edge 90
93
};
94

95
// Target older browsers requiring more polyfills
96
const legacyTargets: Targets = {
97
  chrome: 60 << 16,    // Chrome 60
98
  firefox: 55 << 16,   // Firefox 55
99
  safari: 11 << 16,    // Safari 11
100
  edge: 79 << 16,      // Edge 79
101
  ie: 11 << 16         // Internet Explorer 11
102
};
103

104
// Mobile-focused targeting
105
const mobileTargets: Targets = {
106
  android: 81 << 16,   // Android WebView 81
107
  ios_saf: 13 << 16,   // iOS Safari 13
108
  samsung: 12 << 16    // Samsung Internet 12
109
};
110

111
const result = transform({
112
  filename: "responsive.css",
113
  code: new TextEncoder().encode(`
114
    .hero {
115
      background: linear-gradient(45deg, #ff0000, #00ff00);
116
      display: flex;
117
      gap: clamp(1rem, 2vw, 2rem);
118
      border-radius: max(1rem, 2vw);
119
    }
120
  `),
121
  targets: legacyTargets,
122
  minify: true
123
});
124
```
125

126
### Feature Control
127

128
Control which CSS features are compiled or preserved regardless of browser support.
129

130
```typescript { .api }
131
// Feature flags used in TransformOptions
132
interface TransformOptions<C extends CustomAtRules> {
133
  /** Features that should always be compiled, even when supported by targets. */
134
  include?: number;
135
  /** Features that should never be compiled, even when unsupported by targets. */
136
  exclude?: number;
137
}
138

139
// Features enum (imported from lightningcss)
140
const Features = {
141
  Nesting: 1,
142
  NotSelectorList: 2,
143
  DirSelector: 4,
144
  LangSelectorList: 8,
145
  IsSelector: 16,
146
  TextDecorationThicknessPercent: 32,
147
  MediaIntervalSyntax: 64,
148
  MediaRangeSyntax: 128,
149
  CustomMediaQueries: 256,
150
  ClampFunction: 512,
151
  ColorFunction: 1024,
152
  OklabColors: 2048,
153
  LabColors: 4096,
154
  P3Colors: 8192,
155
  HexAlphaColors: 16384,
156
  SpaceSeparatedColorNotation: 32768,
157
  FontFamilySystemUi: 65536,
158
  DoublePositionGradients: 131072,
159
  VendorPrefixes: 262144,
160
  LogicalProperties: 524288,
161
  LightDark: 1048576,
162
  Selectors: 31,
163
  MediaQueries: 448,
164
  Colors: 1113088,
165
}
166
```
167

168
**Usage Examples:**
169

170
```typescript
171
import { transform, Features } from "lightningcss";
172

173
// Always compile nesting even if browsers support it
174
const alwaysCompileNesting = transform({
175
  filename: "nested.css",
176
  code: new TextEncoder().encode(`
177
    .card {
178
      background: white;
179
      
180
      &:hover {
181
        background: gray;
182
        
183
        .title {
184
          color: blue;
185
        }
186
      }
187
    }
188
  `),
189
  targets: { chrome: 112 << 16 }, // Chrome 112 supports nesting
190
  include: Features.Nesting, // But compile it anyway
191
  minify: true
192
});
193

194
// Never compile color functions, preserve modern syntax
195
const preserveModernColors = transform({
196
  filename: "colors.css",
197
  code: new TextEncoder().encode(`
198
    .modern {
199
      color: lab(50% 20 -30);
200
      background: oklch(60% 0.15 180);
201
      border-color: color(display-p3 1 0 0);
202
    }
203
  `),
204
  targets: { chrome: 70 << 16 }, // Old Chrome doesn't support these
205
  exclude: Features.ColorFunction | Features.OklabColors | Features.P3Colors,
206
  minify: true
207
});
208

209
// Compile multiple features
210
const compileModernFeatures = transform({
211
  filename: "modern.css",
212
  code: new TextEncoder().encode(`
213
    .component {
214
      background: lab(50% 20 -30);
215
      margin-inline: 1rem;
216
      
217
      &:hover {
218
        color: oklch(60% 0.15 180);
219
      }
220
      
221
      @media (width > 768px) {
222
        gap: clamp(1rem, 2vw, 2rem);
223
      }
224
    }
225
  `),
226
  targets: { firefox: 80 << 16, safari: 13 << 16 },
227
  include: Features.Nesting | Features.LogicalProperties | Features.MediaRangeSyntax,
228
  minify: true
229
});
230
```
231

232
### Target-Based Optimization Examples
233

234
Real-world examples of how different targets affect CSS transformation output.
235

236
**Modern Browser Targeting:**
237

238
```typescript
239
const modernCSS = `
240
  .grid {
241
    display: grid;
242
    gap: 1rem;
243
    grid-template-columns: repeat(auto-fit, minmax(min(250px, 100%), 1fr));
244
    color: lab(50% 20 -30);
245
  }
246
  
247
  .card {
248
    container-type: inline-size;
249
    
250
    &:hover {
251
      transform: scale(1.05);
252
    }
253
  }
254
  
255
  @container (width > 300px) {
256
    .card-content { font-size: 1.2rem; }
257
  }
258
`;
259

260
const modernResult = transform({
261
  filename: "modern.css",
262
  code: new TextEncoder().encode(modernCSS),
263
  targets: {
264
    chrome: 105 << 16,
265
    firefox: 100 << 16,
266
    safari: 16 << 16
267
  },
268
  minify: true
269
});
270
// Minimal transformation - most features are preserved
271
```
272

273
**Legacy Browser Targeting:**
274

275
```typescript
276
const legacyResult = transform({
277
  filename: "legacy.css",
278
  code: new TextEncoder().encode(modernCSS),
279
  targets: {
280
    chrome: 60 << 16,
281
    firefox: 55 << 16,
282
    safari: 11 << 16,
283
    ie: 11 << 16
284
  },
285
  minify: true
286
});
287
// Extensive transformation - nesting flattened, modern colors converted, etc.
288
```
289

290
**Progressive Enhancement Pattern:**
291

292
```typescript
293
// Generate multiple CSS files for different browser tiers
294
const baseCss = `
295
  .hero {
296
    background: linear-gradient(45deg, #ff0000, #00ff00);
297
    padding: clamp(1rem, 2vw, 3rem);
298
    
299
    &:hover {
300
      transform: scale(1.02);
301
    }
302
  }
303
`;
304

305
// Base styles for all browsers
306
const baseResult = transform({
307
  filename: "base.css",
308
  code: new TextEncoder().encode(baseCss),
309
  targets: { ie: 11 << 16, chrome: 30 << 16 },
310
  minify: true
311
});
312

313
// Enhanced styles for modern browsers
314
const enhancedResult = transform({
315
  filename: "enhanced.css",
316
  code: new TextEncoder().encode(baseCss + `
317
    .hero-enhanced {
318
      background: conic-gradient(from 45deg, #ff0000, #00ff00, #0000ff);
319
      backdrop-filter: blur(10px);
320
      color: lab(50% 20 -30);
321
    }
322
  `),
323
  targets: { chrome: 90 << 16, firefox: 88 << 16 },
324
  minify: true
325
});
326
```