PostCSS Nested

title="Philosopher’s stone, logo of PostCSS"
src="https://postcss.org/logo-leftp.svg">

[PostCSS] plugin to unwrap nested rules like how Sass does it.

``css
.phone {
&_title {
width: 500px;
@media (max-width: 500px) {
width: auto;
}
body.is_dark & {
color: white;
}
}
img {
display: block;
}
}

.title {
font-size: var(--font);

@at-root html {
--font: 16px
}
}
`

will be processed to:

`css
.phone_title {
width: 500px;
}
@media (max-width: 500px) {
.phone_title {
width: auto;
}
}
body.is_dark .phone_title {
color: white;
}
.phone img {
display: block;
}

.title {
font-size: var(--font);
}
html {
--font: 16px
}
`

Related plugins:

* Use [postcss-atroot] for @at-root at-rule to move nested child
to the CSS root.
* Use [postcss-current-selector] after this plugin if you want
to use current selector in properties or variables values.
* Use [postcss-nested-ancestors] before this plugin if you want
to reference any ancestor element directly in your selectors with ^&.

Alternatives:

* See also [postcss-nesting], which implements [CSSWG draft]
(requires the & and introduces @nest).
* [postcss-nested-props] for nested properties like font-size.


alt="Sponsored by Evil Martians" width="236" height="54">


[postcss-atroot]: https://github.com/OEvgeny/postcss-atroot
[postcss-current-selector]: https://github.com/komlev/postcss-current-selector
[postcss-nested-ancestors]: https://github.com/toomuchdesign/postcss-nested-ancestors
[postcss-nested-props]: https://github.com/jedmao/postcss-nested-props
[postcss-nesting]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-nesting
[CSSWG draft]: https://drafts.csswg.org/css-nesting-1/
[PostCSS]: https://github.com/postcss/postcss

Usage

Step 1: Install plugin:

`sh
npm install --save-dev postcss postcss-nested
`

Step 2: Check your project for existing PostCSS config: postcss.config.js
in the project root, "postcss" section in package.json
or postcss in bundle config.

If you do not use PostCSS, add it according to [official docs]
and set this plugin in settings.

Step 3: Add the plugin to plugins list:

`diff
module.exports = {
plugins: [
+ require('postcss-nested'),
require('autoprefixer')
]
}
`

[official docs]: https://github.com/postcss/postcss#usage

Options

$3

By default, plugin will bubble only @media and @supports at-rules.
You can add your custom at-rules to this list by bubble option:

`js
postcss([ require('postcss-nested')({ bubble: ['phone'] }) ])
`

`css
/ input /
a {
color: white;
@phone {
color: black;
}
}
/ output /
a {
color: white;
}
@phone {
a {
color: black;
}
}
`

$3

By default, plugin will unwrap only @font-face, @keyframes and @document
at-rules. You can add your custom at-rules to this list by unwrap option:

`js
postcss([ require('postcss-nested')({ unwrap: ['phone'] }) ])
`

`css
/ input /
a {
color: white;
@phone {
color: black;
}
}
/ output /
a {
color: white;
}
@phone {
color: black;
}
`

$3

By default, plugin will strip out any empty selector generated by intermediate
nesting levels. You can set preserveEmpty to true to preserve them.

`css
.a {
.b {
color: black;
}
}
`

Will be compiled to:

`css
.a { }
.a .b {
color: black;
}
`

This is especially useful if you want to export the empty classes with postcss-modules`.