Awesome
<div align="center">⚠️ PostCSS Preset Env was moved to <a href="https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-preset-env">@csstools/postcss-plugins</a>. ⚠️ <br> <a href="https://github.com/csstools/postcss-plugins/discussions/75">Read the announcement</a></div>PostCSS Preset Env <img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS" width="90" height="90" align="right">
<img alt="npm version" src="https://img.shields.io/npm/v/postcss-preset-env.svg" height="20"> <img alt="build status" src="https://github.com/csstools/postcss-preset-env/workflows/test/badge.svg" height="20"> <img alt="support chat" src="https://img.shields.io/badge/support-chat-blue.svg" height="20">
PostCSS Preset Env lets you convert modern CSS into something most browsers can understand, determining the polyfills you need based on your targeted browsers or runtime environments.
npm install postcss-preset-env
@custom-media --viewport-medium (width <= 50rem);
@custom-selector :--heading h1, h2, h3, h4, h5, h6;
:root {
--mainColor: #12345678;
}
body {
color: var(--mainColor);
font-family: system-ui;
overflow-wrap: break-word;
}
:--heading {
background-image: image-set(url(img/heading.png) 1x, url(img/heading@2x.png) 2x);
@media (--viewport-medium) {
margin-block: 0;
}
}
a {
color: rgb(0 0 100% / 90%);
&:hover {
color: rebeccapurple;
}
}
/* becomes */
:root {
--mainColor: rgba(18, 52, 86, 0.47059);
}
body {
color: rgba(18, 52, 86, 0.47059);
color: var(--mainColor);
font-family: system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen, Ubuntu, Cantarell, Droid Sans, Helvetica Neue;
word-wrap: break-word;
}
h1, h2, h3, h4, h5, h6 {
background-image: url(img/heading.png);
}
@media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi) {
h1, h2, h3, h4, h5, h6 {
background-image: url(img/heading@2x.png)
}
}
@media (max-width: 50rem) {
h1, h2, h3, h4, h5, h6 {
margin-top: 0;
margin-bottom: 0;
}
}
a {
color: rgba(0, 0, 255, 0.9)
}
a:hover {
color: #639;
}
Without any configuration options, PostCSS Preset Env enables Stage 2 features and supports all browsers.
Usage
Add PostCSS Preset Env to your project:
npm install postcss-preset-env --save-dev
Use PostCSS Preset Env to process your CSS:
const postcssPresetEnv = require('postcss-preset-env');
postcssPresetEnv.process(YOUR_CSS /*, processOptions, pluginOptions */);
Or use it as a PostCSS plugin:
const postcss = require('postcss');
const postcssPresetEnv = require('postcss-preset-env');
postcss([
postcssPresetEnv(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
PostCSS Preset Env runs in all Node environments, with special instructions for:
Node | PostCSS CLI | Webpack | Create React App | Gulp | Grunt | Rollup |
---|
Options
stage
The stage
option determines which CSS features to polyfill, based upon their
stability in the process of becoming implemented web standards.
postcssPresetEnv({ stage: 0 })
The stage
can be 0
(experimental) through 4
(stable), or false
. Setting
stage
to false
will disable every polyfill. Doing this would only be useful
if you intended to exclusively use the features
option.
Without any configuration options, PostCSS Preset Env enables Stage 2 features.
features
The features
option enables or disables specific polyfills by ID. Passing
true
to a specific feature ID will enable its polyfill, while passing false
will disable it. List of IDs
postcssPresetEnv({
/* use stage 3 features + css nesting rules */
stage: 3,
features: {
'nesting-rules': true
}
})
Passing an object to a specific feature ID will both enable and configure it.
postcssPresetEnv({
/* use stage 3 features + css color-mod (warning on unresolved) */
stage: 3,
features: {
'color-mod-function': { unresolved: 'warn' }
}
})
Any polyfills not explicitly enabled or disabled through features
are
determined by the stage
option.
browsers
The browsers
option determines which polyfills are required based upon the
browsers you are supporting.
PostCSS Preset Env supports any standard browserslist configuration, which
can be a .browserslistrc
file, a browserslist
key in package.json
, or
browserslist
environment variables.
The browsers
option should only be used when a standard browserslist
configuration is not available.
postcssPresetEnv({ browsers: 'last 2 versions' })
If not valid browserslist configuration is specified, the default browserslist query will be used.
insertBefore / insertAfter
The insertBefore
and insertAfter
keys allow you to insert other PostCSS
plugins into the chain. This is only useful if you are also using sugary
PostCSS plugins that must execute before or after certain polyfills.
Both insertBefore
and insertAfter
support chaining one or multiple plugins.
import postcssSimpleVars from 'postcss-simple-vars';
postcssPresetEnv({
insertBefore: {
'all-property': postcssSimpleVars
}
})
autoprefixer
PostCSS Preset Env includes autoprefixer and browsers
option
will be passed to it automatically.
Specifying the autoprefixer
option enables passing
additional options
into autoprefixer.
postcssPresetEnv({
autoprefixer: { grid: true }
})
Passing autoprefixer: false
disables autoprefixer.
preserve
The preserve
option determines whether all plugins should receive a
preserve
option, which may preserve or remove otherwise-polyfilled CSS. By
default, this option is not configured.
postcssPresetEnv({
preserve: false // instruct all plugins to omit pre-polyfilled CSS
});
importFrom
The importFrom
option specifies sources where variables like Custom Media,
Custom Properties, Custom Selectors, and Environment Variables can be imported
from, which might be CSS, JS, and JSON files, functions, and directly passed
objects.
postcssPresetEnv({
/*
@custom-media --small-viewport (max-width: 30em);
@custom-selector :--heading h1, h2, h3;
:root { --color: red; }
*/
importFrom: 'path/to/file.css'
});
Multiple sources can be passed into this option, and they will be parsed in the order they are received. JavaScript files, JSON files, functions, and objects will use different namespaces to import different kinds of variables.
postcssPresetEnv({
importFrom: [
/*
@custom-media --small-viewport (max-width: 30em);
@custom-selector :--heading h1, h2, h3;
:root { --color: red; }
*/
'path/to/file.css',
/* module.exports = {
customMedia: { '--small-viewport': '(max-width: 30em)' },
customProperties: { '--color': 'red' },
customSelectors: { ':--heading': 'h1, h2, h3' },
environmentVariables: { '--branding-padding': '20px' }
} */
'and/then/this.js',
/* {
"custom-media": { "--small-viewport": "(max-width: 30em)" }
"custom-properties": { "--color": "red" },
"custom-selectors": { ":--heading": "h1, h2, h3" },
"environment-variables": { "--branding-padding": "20px" }
} */
'and/then/that.json',
{
customMedia: { '--small-viewport': '(max-width: 30em)' },
customProperties: { '--color': 'red' },
customSelectors: { ':--heading': 'h1, h2, h3' },
environmentVariables: { '--branding-padding': '20px' }
},
() => {
const customMedia = { '--small-viewport': '(max-width: 30em)' };
const customProperties = { '--color': 'red' };
const customSelectors = { ':--heading': 'h1, h2, h3' };
const environmentVariables = { '--branding-padding': '20px' };
return { customMedia, customProperties, customSelectors, environmentVariables };
}
]
});
exportTo
The exportTo
option specifies destinations where variables like Custom Media,
Custom Properties, Custom Selectors, and Environment Variables can be exported
to, which might be CSS, JS, and JSON files, functions, and directly passed
objects.
postcssPresetEnv({
/*
@custom-media --small-viewport (max-width: 30em);
@custom-selector :--heading h1, h2, h3;
:root { --color: red; }
*/
exportTo: 'path/to/file.css'
});
Multiple destinations can be passed into this option as well, and they will be parsed in the order they are received. JavaScript files, JSON files, and objects will use different namespaces to import different kinds of variables.
const cachedObject = {};
postcssPresetEnv({
exportTo: [
/*
@custom-media --small-viewport (max-width: 30em);
@custom-selector :--heading h1, h2, h3;
:root { --color: red; }
*/
'path/to/file.css',
/* module.exports = {
customMedia: { '--small-viewport': '(max-width: 30em)' },
customProperties: { '--color': 'red' },
customSelectors: { ':--heading': 'h1, h2, h3' },
environmentVariables: { '--branding-padding': '20px' }
} */
'and/then/this.js',
/* {
"custom-media": { "--small-viewport": "(max-width: 30em)" }
"custom-properties": { "--color": "red" },
"custom-selectors": { ":--heading": "h1, h2, h3" },
"environment-variables": { "--branding-padding": "20px" }
} */
'and/then/that.json',
cachedObject,
variables => {
if ('customProperties' in variables) {
// do something special with customProperties
}
Object.assign(cachedObject, variables);
}
]
});