skip to content

In postcss-preset-env, what do the stage and features options control, and why does it leave some modern CSS untransformed?

level: middleimportance: should knowfreq 8%

answer

  1. a pack of polyfill plugins
  2. spec maturity, 0 to 4
  3. default stage 2
  4. per-feature IDs override the stage
  5. skipped when every target supports it

basics

~20 s

postcss-preset-env picks features by spec maturity (stage, 0 to 4 or false, default 2) and per-feature overrides (features), then lowers a feature only if a Browserslist target lacks support. Syntax every target supports passes through untouched.

solid answer

~40 s

postcss-preset-env is a plugin pack that lowers standard CSS features using support data from Can I Use and MDN. `stage` sets the minimum spec maturity, from `0` (experimental) to `4` (stable), or `false` to turn off stage-based selection; in postcss-preset-env 11 the default is `2`. `features` overrides single features by ID: `true` forces one on, even when every target supports it; `false` disables it; an object configures it; and `['auto', {...}]` configures it while keeping automatic selection. A selected feature is still lowered only when one of the Browserslist targets lacks support, so syntax every target handles passes through untouched. It runs Autoprefixer inside itself with the same targets. It handles only standard CSS: spec nesting comes from postcss-nesting under the `nesting-rules` ID, while Sass-style nesting needs postcss-nested placed before the preset.

code

javascript · 16 lines
javascript
const postcssPresetEnv = require('postcss-preset-env')

module.exports = {
  plugins: [
    require('postcss-import')(),
    postcssPresetEnv({
      stage: 3,                                   // stage 3 or later...
      features: {
        'nesting-rules': true,                    // ...plus spec nesting, forced on
        'custom-selectors': ['auto', { preserve: true }]
      },
      debug: true                                 // log why each feature is on or off
    }),
    require('cssnano')()
  ]
}

go deeper

for a junior

Recall that postcss-preset-env lowers newer CSS for older browsers and includes Autoprefixer, so it is one config entry rather than many.

for a middle

Explain the stage scale and its default of 2, the features overrides by ID, and how the Browserslist targets decide whether a selected feature is actually transformed.

for a senior

Use debug output to explain a surprising result, know that forcing a feature with true bypasses the target check, and keep non-standard plugins before the pack.

for a principal

Decide how much draft CSS a codebase may depend on: a stage floor and explicit feature list as policy, weighed against fallbacks that never leave the bundle.

## What postcss-preset-env is **postcss-preset-env** is a **plugin pack**: one entry in the PostCSS config that expands into dozens of polyfill plugins plus Autoprefixer. It tracks CSS features through the cssdb list, where each feature has a **spec stage** and browser support data from Can I Use and MDN. In the common case, three questions decide whether a given feature is transformed: 1. Is the feature **selected**, by its stage or by an explicit `features` entry? 2. Does any **target browser** lack support for it? (A feature forced on with `true` skips this check.) 3. Has it been **disabled** explicitly? The numbers below are for postcss-preset-env 11 (11.6.1 at the time of writing). ## `stage`: how mature a feature must be | Value | Meaning | |---|---| | `0` | experimental drafts are included | | `1`-`3` | increasingly mature proposals | | `4` | stable standards only | | `false` | no stage-based selection; only what `features` enables | | unset | **`2`** | The README warns that features rarely progress beyond stage 2, and suggests the `minimumVendorImplementations` option (default `0`) for teams that would rather select by how many browser engines ship a feature. ## `features`: per-feature overrides `features` takes feature IDs from the preset's feature list: - `true` **forces** a feature on. It is lowered even if every target browser already supports it, because an explicit choice skips the support check. - `false` disables it, whatever the stage. - An **object** both enables and configures it, for example `{ preserve: true }` to keep the original syntax next to the fallback. - `['auto', { ... }]` configures it but keeps automatic selection by stage and targets. Features not named in `features` follow the `stage` rule. ## Why modern CSS is often left alone After selection, the preset compares each feature's unsupported-browser list with your **Browserslist targets**, read from `.browserslistrc`, the `browserslist` key in `package.json` or the Browserslist environment variables. The `env` option picks a named environment (when neither the option nor the Browserslist environment variables name one, `production`); the `browsers` option overrides the config entirely, and should only be used when no shared config exists. If no target lacks support, the feature is skipped. With `debug: true` the preset logs lines such as "disabled because all targeted browsers support it". The README sums it up: as targets change, the bundle only ever contains the fallbacks still needed. For the exhibition-guide site, adding older kiosk iPads to the targets is what turns lowering on for features those devices lack. The CSS itself does not change. ## What the pack contains, and what it does not - **Autoprefixer** runs inside the preset with the same `env` / `browsers`. Pass options through the `autoprefixer` key, disable it with `autoprefixer: false`, and remove any standalone copy. - **Nesting**: the `nesting-rules` feature uses **postcss-nesting**, which follows the CSS Nesting specification. **postcss-nested** is a different plugin that unwraps nesting the way Sass does, and it is not part of the pack. Because it is non-standard, it must run before the preset. - **Client-side polyfills**: a few features need a browser library; they stay off unless `enableClientSidePolyfills` is set. - **Non-standard syntax** of any kind is out of scope. The pack only contains plugins for features on a standards track. ## A configuration to reason about The example asks for stage 3 or later and forces spec nesting on even where targets support it. It keeps `custom-selectors` on automatic selection while preserving the original selector, and turns on debug logging. Reading the log after a build is the fastest way to answer "why did this feature not change?" ## Common surprises - **"preset-env did nothing to my nesting."** Every target already supports it, so the feature was skipped. That is correct behaviour, not a bug. - **"Old browsers still break."** Either the feature sits below the configured stage, or it needs a client-side polyfill that is off by default, or the targets never included those browsers. The debug log names which of the three it is. - **"The output grew after an upgrade."** A wider target list, or a feature forced on with `true`, adds fallbacks, and many plugins keep the original syntax next to each fallback unless `preserve: false` is set. - **"Prefixes appear twice."** A standalone Autoprefixer is still listed next to the pack.

  • What does `stage: false` leave running in postcss-preset-env?
    It turns off stage-based selection, so only the features you enable under `features` are applied. Autoprefixer still runs, because it is controlled separately by the `autoprefixer` option, so you still get prefixes for your targets unless you set `autoprefixer: false`.
  • When would you use `minimumVendorImplementations` alongside `stage`?
    The README notes that features rarely progress beyond stage 2, so stage alone can lag behind what browsers ship. `minimumVendorImplementations` (0 to 3, default 0) selects features by how many browser engines implement them; 2 is the README's suggestion for stable features. Both filters apply together, and `features` overrides either.

  • postcss-preset-env defaults to stage 0, so every draft feature is on.
  • It transforms every modern feature regardless of the browsers you target.
  • Setting a feature to true still skips it when every target supports it.
  • postcss-nesting and postcss-nested are two names for the same plugin.
  • You still need a separate autoprefixer entry next to postcss-preset-env.