https://github.com/postcss/postcss-nested
PostCSS plugin to unwrap nested rules like how Sass does it.
https://github.com/postcss/postcss-nested
Last synced: 10 months ago
JSON representation
PostCSS plugin to unwrap nested rules like how Sass does it.
- Host: GitHub
- URL: https://github.com/postcss/postcss-nested
- Owner: postcss
- License: mit
- Created: 2014-11-07T23:14:54.000Z (over 11 years ago)
- Default Branch: main
- Last Pushed: 2024-12-17T07:09:01.000Z (about 1 year ago)
- Last Synced: 2025-05-11T05:46:10.324Z (10 months ago)
- Language: JavaScript
- Homepage:
- Size: 835 KB
- Stars: 1,183
- Watchers: 13
- Forks: 66
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# PostCSS Nested
[PostCSS] plugin to unwrap nested rules closer to Sass syntax.
```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-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].
- [`postcss-nested-props`] for nested properties like `font-size`.
[`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
### `bubble`
By default, plugin will bubble only `@media`, `@supports`, `@layer`,
`@container`, and `@starting-style` at-rules. Use this option
to add your custom at-rules to this list.
```js
postcss([require('postcss-nested')({ bubble: ['phone'] })])
```
```css
/* input */
a {
color: white;
@phone {
color: black;
}
}
/* output */
a {
color: white;
}
@phone {
a {
color: black;
}
}
```
### `unwrap`
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;
}
```
### `preserveEmpty`
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`.
### `rootRuleName`
The plugin supports the SCSS custom at-rule `@at-root` which breaks rule
blocks out of their nested position. If you want, you can choose a new
custom name for this rule in your code.
```js
postcss([require('postcss-nested')({ rootRuleName: '_escape-nesting' })])
```
```css
/* input */
.a {
color: white;
@_escape-nesting {
.b {
color: black;
}
}
}
/* output */
.a {
color: white;
}
.b {
color: black;
}
```