PostCSS Cascade Layers

PostCSS Cascade Layers lets you use @layer following the Cascade Layers Specification. For more information on layers, checkout A Complete Guide to CSS Cascade Layers by Miriam Suzanne.

target {
    color: purple;
}

@layer {
    target {
        color: green;
    }
}


/* becomes */


target:not(#\#) {
    color: purple;
}

target {
        color: green;
    }

Usage

Add PostCSS Cascade Layers to your project:

npm install postcss @csstools/postcss-cascade-layers --save-dev

Use it as a PostCSS plugin:

const postcss = require('postcss');
const postcssCascadeLayers = require('@csstools/postcss-cascade-layers');

postcss([
    postcssCascadeLayers(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);

PostCSS Cascade Layers runs in all Node environments, with special instructions for:

Options

onRevertLayerKeyword

The onRevertLayerKeyword option enables warnings if revert-layer is used. Transforming revert-layer for older browsers is not possible in this plugin.

Defaults to warn

postcssCascadeLayers({ onRevertLayerKeyword: 'warn' }) // 'warn' | false

/* [postcss-cascade-layers]: handling "revert-layer" is unsupported by this plugin and will cause style differences between browser versions. */
@layer {
    .foo {
        color: revert-layer;
    }
}

onConditionalRulesChangingLayerOrder

The onConditionalRulesChangingLayerOrder option enables warnings if layers are declared in multiple different orders in conditional rules. Transforming these layers correctly for older browsers is not possible in this plugin.

Defaults to warn

postcssCascadeLayers({ onConditionalRulesChangingLayerOrder: 'warn' }) // 'warn' | false

/* [postcss-cascade-layers]: handling different layer orders in conditional rules is unsupported by this plugin and will cause style differences between browser versions. */
@media (min-width: 10px) {
    @layer B {
        .foo {
            color: red;
        }
    }
}

@layer A {
    .foo {
        color: pink;
    }
}

@layer B {
    .foo {
        color: red;
    }
}

onImportLayerRule

The @import at-rule can also be used with cascade layers, specifically to create a new layer like so:

@import 'theme.css' layer(utilities);

If your CSS uses @import with layers, you will also need the postcss-import plugin. This plugin alone will not handle the @import at-rule.

This plugin will warn you when it detects that postcss-import did not transform@import at-rules.

postcssCascadeLayers({ onImportLayerRule: 'warn' }) // 'warn' | false

Contributors

The contributors to this plugin were Olu Niyi-Awosusi and Sana Javed from Oddbird and Romain Menke.