0
# Plugin Configuration
1

2
Comprehensive configuration options for controlling PostCSS Preset Env's behavior, including feature stages, browser targeting, autoprefixer integration, and debugging capabilities.
3

4
## Capabilities
5

6
### Main Plugin Creator
7

8
Creates a PostCSS plugin with the specified configuration options.
9

10
```typescript { .api }
11
/**
12
 * Creates a PostCSS preset environment plugin
13
 * @param options - Configuration options for the plugin
14
 * @returns PostCSS plugin instance
15
 */
16
declare function postcssPresetEnv(options?: pluginOptions): PostCSS.Plugin;
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
// Basic usage with default stage 2 features
23
const plugin = postcssPresetEnv();
24

25
// Target specific browsers
26
const plugin = postcssPresetEnv({
27
  browsers: ['> 1%', 'last 2 versions']
28
});
29

30
// Enable all stage 3 features
31
const plugin = postcssPresetEnv({
32
  stage: 3
33
});
34

35
// Disable autoprefixer
36
const plugin = postcssPresetEnv({
37
  autoprefixer: false
38
});
39
```
40

41
### Stage-based Feature Control
42

43
Control which CSS features are polyfilled based on their standardization stage.
44

45
```typescript { .api }
46
interface StageOptions {
47
  /**
48
   * Determine which CSS features to polyfill based on standardization stage
49
   * - Stage 0: Experimental features
50
   * - Stage 1: Working draft features
51
   * - Stage 2: Candidate recommendation (default)
52
   * - Stage 3: Recommendation features
53
   * - Stage 4: Web standard features
54
   * - false: Disable stage-based feature selection
55
   */
56
  stage?: number | false;
57
  
58
  /**
59
   * Minimum number of vendor implementations required for a feature
60
   * Features with fewer implementations will be skipped
61
   * @default 0
62
   */
63
  minimumVendorImplementations?: number;
64
}
65
```
66

67
**Usage Examples:**
68

69
```javascript
70
// Only use well-established features (stage 3+)
71
postcssPresetEnv({ stage: 3 });
72

73
// Use experimental features (stage 0+)
74
postcssPresetEnv({ stage: 0 });
75

76
// Disable stage filtering, rely on browser support only
77
postcssPresetEnv({ stage: false });
78

79
// Require at least 2 vendor implementations
80
postcssPresetEnv({ minimumVendorImplementations: 2 });
81
```
82

83
### Browser Targeting
84

85
Configure which browsers to support using Browserslist integration.
86

87
```typescript { .api }
88
interface BrowserTargeting {
89
  /**
90
   * Browserslist environment name for multi-environment configs
91
   * Used when .browserslistrc or package.json has multiple environments
92
   */
93
  env?: string;
94
  
95
  /**
96
   * Override browser targets directly
97
   * When specified, ignores .browserslistrc and package.json browserslist
98
   * Takes precedence over env option
99
   */
100
  browsers?: string | string[] | null;
101
}
102
```
103

104
**Usage Examples:**
105

106
```javascript
107
// Use specific browserslist environment
108
postcssPresetEnv({ env: 'production' });
109

110
// Override browser targets
111
postcssPresetEnv({
112
  browsers: ['> 1%', 'last 2 versions', 'Firefox ESR']
113
});
114

115
// Support only modern browsers
116
postcssPresetEnv({
117
  browsers: ['last 1 Chrome version', 'last 1 Firefox version']
118
});
119
```
120

121
### CSS Preservation Options
122

123
Control whether original CSS is preserved alongside polyfilled versions.
124

125
```typescript { .api }
126
interface PreservationOptions {
127
  /**
128
   * Global preserve setting for all plugins
129
   * Individual plugins may override this default
130
   * When undefined, each plugin uses its own default
131
   */
132
  preserve?: boolean;
133
}
134
```
135

136
**Usage Examples:**
137

138
```javascript
139
// Preserve original CSS alongside polyfills
140
postcssPresetEnv({ preserve: true });
141

142
// Remove original CSS, keep only polyfills
143
postcssPresetEnv({ preserve: false });
144
```
145

146
### Autoprefixer Integration
147

148
Configure the built-in autoprefixer functionality.
149

150
```typescript { .api }
151
interface AutoprefixerOptions {
152
  /**
153
   * Autoprefixer configuration or false to disable
154
   * Shares browser targets with the main plugin
155
   * @default autoprefixer enabled with shared targets
156
   */
157
  autoprefixer?: autoprefixer.Options | false;
158
}
159
```
160

161
**Usage Examples:**
162

163
```javascript
164
// Disable autoprefixer
165
postcssPresetEnv({ autoprefixer: false });
166

167
// Configure autoprefixer options
168
postcssPresetEnv({
169
  autoprefixer: {
170
    grid: 'autoplace',
171
    remove: false
172
  }
173
});
174
```
175

176
### Plugin Insertion Control
177

178
Insert custom PostCSS plugins before or after specific features.
179

180
```typescript { .api }
181
interface PluginInsertion {
182
  /**
183
   * Insert plugins before specific features
184
   * Key is feature ID, value is plugin or array of plugins
185
   */
186
  insertBefore?: Record<string, unknown>;
187
  
188
  /**
189
   * Insert plugins after specific features
190
   * Key is feature ID, value is plugin or array of plugins
191
   */
192
  insertAfter?: Record<string, unknown>;
193
}
194
```
195

196
**Usage Examples:**
197

198
```javascript
199
import customPlugin from 'my-custom-plugin';
200

201
postcssPresetEnv({
202
  insertBefore: {
203
    'custom-properties': customPlugin()
204
  },
205
  insertAfter: {
206
    'nesting-rules': [plugin1(), plugin2()]
207
  }
208
});
209
```
210

211
### Debug and Development Options
212

213
Enable debugging output and development assistance.
214

215
```typescript { .api }
216
interface DebugOptions {
217
  /**
218
   * Enable debug output showing which features are enabled/disabled
219
   * Logs to PostCSS result messages
220
   * @default false
221
   */
222
  debug?: boolean;
223
  
224
  /**
225
   * Enable client-side polyfills requiring runtime JavaScript
226
   * Most features work with CSS-only transforms
227
   * @default false
228
   */
229
  enableClientSidePolyfills?: boolean;
230
}
231
```
232

233
**Usage Examples:**
234

235
```javascript
236
// Enable debug logging
237
postcssPresetEnv({ debug: true });
238

239
// Enable features requiring client-side JavaScript
240
postcssPresetEnv({ enableClientSidePolyfills: true });
241
```
242

243
### Logical Properties Configuration
244

245
Global configuration for logical properties and directions.
246

247
```typescript { .api }
248
interface LogicalConfiguration {
249
  /**
250
   * Configure logical properties behavior globally
251
   * Affects all logical property plugins at once
252
   */
253
  logical?: {
254
    /** Set the inline flow direction (default: left-to-right) */
255
    inlineDirection?: DirectionFlow;
256
    /** Set the block flow direction (default: top-to-bottom) */
257
    blockDirection?: DirectionFlow;
258
  };
259
}
260
```
261

262
**Usage Examples:**
263

264
```javascript
265
// Configure right-to-left layout
266
postcssPresetEnv({
267
  logical: {
268
    inlineDirection: 'right-to-left',
269
    blockDirection: 'top-to-bottom'
270
  }
271
});
272
```
273

274
## Complete Configuration Interface
275

276
```typescript { .api }
277
interface pluginOptions {
278
  stage?: number | false;
279
  minimumVendorImplementations?: number;
280
  enableClientSidePolyfills?: boolean;
281
  env?: string;
282
  browsers?: string | string[] | null;
283
  preserve?: boolean;
284
  autoprefixer?: autoprefixer.Options | false;
285
  features?: pluginsOptions;
286
  insertBefore?: Record<string, unknown>;
287
  insertAfter?: Record<string, unknown>;
288
  debug?: boolean;
289
  logical?: {
290
    inlineDirection?: DirectionFlow;
291
    blockDirection?: DirectionFlow;
292
  };
293
}
294
```