@oat-sa/postcss-preset-env

PostCSS Preset Env

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/[e-mail]) 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/[e-mail])
  }
}

@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);
    }
  ]
});

Changelog

7.0.0 (November 16, 2021)

• Updated autoprefixer to 10.4.0 (major)
• Updated browserslist to 4.17.5 (minor)
• Updated caniuse-lite to 1.0.30001272 (patch)
• Updated css-blank-pseudo to 2.0.0 (major)
• Updated css-has-pseudo to 2.0.0 (major)
• Updated css-prefers-color-scheme to 5.0.0 (major)
• Updated cssdb to 5.0.0 (major)
• Updated postcss to 8.3.0 (major)
• Updated postcss-attribute-case-insensitive to 5.0.0 (major)
• Updated postcss-color-functional-notation to 4.0.0 (major)
• Updated postcss-color-hex-alpha to 8.0.0 (major)
• Updated postcss-color-rebeccapurple to 7.0.0 (major)
• Updated postcss-custom-media to 8.0.0 (major)
• Updated postcss-custom-properties to 12.0.0 (major)
• Updated postcss-custom-selectors to 6.0.0 (major)
• Updated postcss-dir-pseudo-class to 6.0.0 (major)
• Updated postcss-double-position-gradients to 3.0.0 (major)
• Updated postcss-env-function to 4.0.1 (major)
• Updated postcss-focus-visible to 6.0.1 (major)
• Updated postcss-focus-within to 5.0.1 (major)
• Updated postcss-font-variant to 5.0.0 (major)
• Updated postcss-gap-properties to 3.0.0 (major)
• Updated postcss-image-set-function to 4.0.0 (major)
• Updated postcss-initial to 3.0.4 (patch)
• Updated postcss-lab-function to 4.0.0 (major)
• Updated postcss-logical to 5.0.0 (major)
• Updated postcss-media-minmax to 5.0.0 (major)
• Updated postcss-nesting to 10.0.0 (major)
• Updated postcss-overflow-shorthand to 3.0.0 (major)
• Updated postcss-page-break to 3.0.4 (major)
• Updated postcss-place to 7.0.0 (major)
• Updated postcss-pseudo-class-any-link to 7.0.0 (major)
• Updated postcss-replace-overflow-wrap to 4.0.0 (major)
• Removed postcss-selector-matches
• Removed postcss-color-gray
• Updated support for Node 12+ (major)