postcss-nested-once

1.0.0 verified Mon Apr 27 auth: no javascript

PostCSS plugin that unwraps nested CSS rules (Sass-like), specifically designed to work correctly with CSS Modules in rollup-plugin-styles. Version 1.0.0, stable. Unlike postcss-nested, it processes nested selectors with the ampersand (&) before CSS Modules scope resolution, ensuring exported class names like `list_item` are generated correctly. It uses the Once hook and the `@nest` at-rule behavior. Ships TypeScript types.

Common errors

error Cannot find module 'postcss-nested-once' ↓

cause Package not installed or incorrect import path.

fix

Install: npm install postcss-nested-once --save-dev

error TypeError: postcssNestedOnce is not a function ↓

cause Importing the package but not calling it as a function.

fix

Use postcssNestedOnce() (with parentheses) in plugins array.

error Cannot read properties of undefined (reading 'list_item') ↓

cause Using postcss-nested instead of postcss-nested-once; ampersand-combined selectors not generating correct class names.

fix

Replace postcss-nested with postcss-nested-once in plugins.

Warnings

gotcha Only works correctly when placed before CSS Modules plugins in the PostCSS pipeline (as done in rollup-plugin-styles). If used outside that context, behavior may differ. ↓

fix Ensure plugin order: nested-once before modules scope resolution.

gotcha Does not support all Sass-like nesting features. It focuses on ampersand-combined selectors (e.g., `&_item`). Complex nested rules without ampersand may not behave as expected. ↓

fix Test your CSS; for full Sass nesting, use postcss-nested instead.

gotcha Requires PostCSS 8.3.5 or higher. Older PostCSS versions will not work. ↓

fix Update postcss to ^8.3.5.

Install

npm install postcss-nested-once

yarn add postcss-nested-once

pnpm add postcss-nested-once

Imports

default

wrong

const postcssNestedOnce = require('postcss-nested-once').default

correct

import postcssNestedOnce from 'postcss-nested-once'

Default export is a function that creates the PostCSS plugin.

n/a (plugin factory)
wrong
```
postcssNestedOnce (without calling as function)
```
correct
```
postcssNestedOnce() in PostCSS plugins array
```
Must be called as a function to produce a plugin instance; passing the function directly will error.

n/a (CommonJS)

wrong

const postcssNestedOnce = require('postcss-nested-once').default

correct

const postcssNestedOnce = require('postcss-nested-once')

CJS import is straightforward; using .default is incorrect and yields undefined.

Quickstart

Shows how to configure rollup-plugin-styles with postcss-nested-once for CSS Modules support with nested ampersand selectors.

// rollup.config.js
import styles from 'rollup-plugin-styles';
import postcssNestedOnce from 'postcss-nested-once';

export default {
  plugins: [
    styles({
      mode: 'inject',
      modules: true,
      plugins: [
        postcssNestedOnce(),
      ],
    }),
  ],
};