0
# PostCSS Preset Env
1
2
PostCSS Preset Env converts modern CSS into something browsers understand, determining the polyfills you need based on your targeted browsers or runtime environments. It combines 60+ CSS feature polyfills with autoprefixer functionality, automatically enabling features based on browser support data from CSSDB.
3
4
## Package Information
5
6
- **Package Name**: postcss-preset-env
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install postcss-preset-env`
10
11
## Core Imports
12
13
```javascript
14
const postcssPresetEnv = require('postcss-preset-env');
15
```
16
17
ES Modules:
18
19
```javascript
20
import postcssPresetEnv from 'postcss-preset-env';
21
```
22
23
## Basic Usage
24
25
```javascript
26
import postcss from 'postcss';
27
import postcssPresetEnv from 'postcss-preset-env';
28
29
const css = `
30
:root {
31
--mainColor: #12345678;
32
}
33
34
body {
35
color: var(--mainColor);
36
font-family: system-ui;
37
}
38
39
.heading {
40
background-image: image-set(url(img/heading.png) 1x, url(img/heading@2x.png) 2x);
41
}
42
43
a:hover {
44
color: rebeccapurple;
45
}
46
`;
47
48
const result = await postcss([
49
postcssPresetEnv({
50
stage: 2,
51
features: {
52
'nesting-rules': true,
53
'custom-properties': false
54
}
55
})
56
]).process(css, { from: 'src/app.css', to: 'dist/app.css' });
57
58
console.log(result.css);
59
```
60
61
## Architecture
62
63
PostCSS Preset Env is built around several key components:
64
65
- **Plugin Creator Function**: Main export that accepts configuration and returns a PostCSS plugin
66
- **Feature System**: 60+ individual CSS feature plugins that can be enabled/disabled
67
- **Stage-based Control**: Features organized by CSS specification stages (0-4)
68
- **Browser Targeting**: Integration with Browserslist for automatic feature detection
69
- **Autoprefixer Integration**: Built-in vendor prefix handling
70
- **Type Safety**: Full TypeScript support with comprehensive type definitions
71
72
## Capabilities
73
74
### Core Plugin Configuration
75
76
The main plugin creator function with comprehensive configuration options for controlling CSS feature polyfills, browser targeting, and plugin behavior.
77
78
```typescript { .api }
79
declare function postcssPresetEnv(options?: pluginOptions): PostCSS.Plugin;
80
81
interface pluginOptions {
82
/** CSS feature stage control (0-4, default: 2) */
83
stage?: number | false;
84
/** Minimum vendor implementations required (default: 0) */
85
minimumVendorImplementations?: number;
86
/** Enable client-side polyfills (default: false) */
87
enableClientSidePolyfills?: boolean;
88
/** Browserslist environment name */
89
env?: string;
90
/** Browser targets override */
91
browsers?: string | string[] | null;
92
/** Preserve original CSS (default: varies by plugin) */
93
preserve?: boolean;
94
/** Autoprefixer configuration */
95
autoprefixer?: autoprefixer.Options | false;
96
/** Individual feature configuration */
97
features?: pluginsOptions;
98
/** Insert plugins before specific features */
99
insertBefore?: Record<string, unknown>;
100
/** Insert plugins after specific features */
101
insertAfter?: Record<string, unknown>;
102
/** Enable debug output (default: false) */
103
debug?: boolean;
104
/** Logical properties configuration */
105
logical?: LogicalOptions;
106
}
107
```
108
109
[Plugin Configuration](./plugin-configuration.md)
110
111
### CSS Feature Polyfills
112
113
Individual CSS feature polyfills that can be enabled, disabled, or configured. Features are organized by CSS specification stages and automatically enabled based on browser support.
114
115
```typescript { .api }
116
interface pluginsOptions {
117
/** CSS Color Module Level 4 features */
118
'color-function'?: subPluginOptions<ColorFunctionOptions>;
119
'color-mix'?: subPluginOptions<ColorMixOptions>;
120
'hwb-function'?: subPluginOptions<HWBFunctionOptions>;
121
'lab-function'?: subPluginOptions<LabFunctionOptions>;
122
'oklab-function'?: subPluginOptions<OklabFunctionOptions>;
123
'hexadecimal-alpha-notation'?: subPluginOptions<HexAlphaOptions>;
124
'color-functional-notation'?: subPluginOptions<ColorFunctionalNotationOptions>;
125
'rebeccapurple-color'?: subPluginOptions<RebeccapurpleOptions>;
126
127
/** CSS Logical Properties */
128
'logical-properties-and-values'?: subPluginOptions<LogicalPropertiesOptions>;
129
'logical-overflow'?: subPluginOptions<LogicalOverflowOptions>;
130
'logical-overscroll-behavior'?: subPluginOptions<LogicalOverscrollOptions>;
131
'logical-resize'?: subPluginOptions<LogicalResizeOptions>;
132
'logical-viewport-units'?: subPluginOptions<LogicalViewportOptions>;
133
'float-clear-logical-values'?: subPluginOptions<FloatClearLogicalOptions>;
134
135
/** CSS Selectors Level 4 */
136
'is-pseudo-class'?: subPluginOptions<IsPseudoOptions>;
137
'has-pseudo-class'?: subPluginOptions<HasPseudoOptions>;
138
'focus-visible-pseudo-class'?: subPluginOptions<FocusVisibleOptions>;
139
'focus-within-pseudo-class'?: subPluginOptions<FocusWithinOptions>;
140
'any-link-pseudo-class'?: subPluginOptions<AnyLinkOptions>;
141
'dir-pseudo-class'?: subPluginOptions<DirPseudoOptions>;
142
'not-pseudo-class'?: subPluginOptions<NotPseudoOptions>;
143
144
/** And 40+ additional features... */
145
}
146
147
type subPluginOptions<T> = ['auto' | boolean, T] | T | boolean;
148
```
149
150
[CSS Features](./css-features.md)
151
152
### Type Definitions
153
154
Core type definitions used throughout the plugin system, including enums for logical directions and configuration interfaces.
155
156
```typescript { .api }
157
enum DirectionFlow {
158
TopToBottom = 'top-to-bottom',
159
BottomToTop = 'bottom-to-top',
160
RightToLeft = 'right-to-left',
161
LeftToRight = 'left-to-right'
162
}
163
164
interface LogicalOptions {
165
/** Set the inline flow direction (default: left-to-right) */
166
inlineDirection?: DirectionFlow;
167
/** Set the block flow direction (default: top-to-bottom) */
168
blockDirection?: DirectionFlow;
169
}
170
```
171
172
[Type Definitions](./type-definitions.md)