Diagnosing PostCSS Nesting Issues with postcss-nesting

Recognizable condition

When you run a build (e.g., npm run build or vite build) the generated CSS file still contains raw nesting symbols such as & or @nest instead of flattened selectors like .parent .child. This indicates that the PostCSS nesting transformation did not execute.

Cause and diagnostic overview

Possible cause	What to look for
Missing postcss-nesting plugin	The plugin is absent from the plugins array in postcss.config.js.
Incorrect plugin order	postcss-nesting appears after autoprefixer or other transformation plugins that expect flat selectors.
Configuration not loaded	The PostCSS runner (Webpack, Vite, CLI) falls back to a default config or ignores the file.
Syntax mismatch	Using Sass‑style nesting (.parent { .child { } }) which postcss-nesting does not interpret.

Ordered checks

1. Verify the plugin is installed
   Run the command in your project root:
   

   npm list postcss-nesting

   or with Yarn:
   

   yarn list postcss-nesting

   Required permission: read access to node_modules. Risk: none; the command only reads the lockfile.
2. Inspect the PostCSS configuration
   Open postcss.config.js and confirm the plugins array includes require('postcss-nesting') before any prefixing plugins. Example:

   module.exports = {
     plugins: [
       require('postcss-nesting'),
       require('autoprefixer')
     ]
   };
   

   Check that the file is actually being loaded by adding a temporary console.log:

   console.log('PostCSS config loaded');
   module.exports = { plugins: [require('postcss-nesting')] };
   

   Run the build and look for the log in the terminal.
3. Confirm the runner is using the config
   For Webpack, check the loader options:

   {
     loader: 'postcss-loader',
     options: { postcssOptions: { config: path.resolve(__dirname, 'postcss.config.js') } }
   }
   

   For Vite, ensure postcss.config.js is in the project root (Vite picks it up automatically). For the CLI, run:

   postcss src/styles.css -o dist/styles.css --config postcss.config.js

   Check: the output mentions the config path or the temporary log appears.
4. Validate the nesting syntax
   Make sure you use the spec‑compliant form with the ampersand:

   .parent {
     &.child {
       color: red;
     }
   }
   

   Avoid Sass‑style nesting without the ampersand, as postcss-nesting will leave it unchanged.
5. Inspect the generated CSS
   After the build, open the output file and search for & or @nest. If they are absent, the transformation succeeded.

Fixes tied to findings

• If Check 1 shows the plugin missing, install it:

  npm install --save-dev postcss-nesting

  or yarn add -D postcss-nesting. Then add it to the plugins array as shown above.
• If Check 2 reveals the plugin is after autoprefixer, reorder the array so postcss-nesting comes first.
• If Check 3 indicates the config is not being loaded, explicitly pass the config path to the runner (see the Webpack/Vite/CLI examples) or move the file to the project root.
• If Check 4 finds Sass‑style nesting, rewrite the rules using the ampersand or switch to postcss-nested (which understands Sass syntax) but note that the two plugins are not interchangeable.

Escalation criteria

If after completing all checks the output still contains raw nesting symbols:

1. Confirm you are using a compatible PostCSS core version (≥ 8.0) and that postcss-nesting version matches the range specified in its documentation (usually ^6.0.0 for PostCSS 8).
2. Check for other plugins that may re‑nest selectors after postcss-nesting (e.g., certain CSS‑modules plugins). Temporarily disable them to isolate the issue.
3. Run the PostCSS CLI directly on a minimal test file to rule out build‑tool interference:

   echo ".parent { &.child { color: red; } }" > test.css
   postcss test.css -o test.out.css --config postcss.config.js
   

   If the CLI output is correct, the problem lies in the build tool configuration; otherwise, revisit the plugin version compatibility.

Limitations and practical verification

This guide assumes you are using the spec‑compliant postcss-nesting plugin. If you rely on postcss-nested (Sass‑like syntax) the diagnostic steps differ. To verify a fix, build the project and open the generated CSS in a browser inspector; the rules should appear as flat selectors (e.g., .parent .child) and apply correctly to the DOM. No further tooling is required.