cssnano Utilities

Common errors

• Error: PostCSS plugin <plugin-name> was not found

  cause The PostCSS plugin provided by `cssnano-utils` (e.g., `rawCache`) was not correctly imported or passed to PostCSS.
  fix Ensure `import { rawCache } from 'cssnano-utils';` is used and `rawCache()` is included in the `postcss` plugin array: `postcss([rawCache()])`.

• TypeError: Cannot read properties of undefined (reading 'walkDecls')

  cause This usually indicates that a PostCSS `root` or `node` object is `undefined` when attempting to traverse the AST, often due to an empty CSS input or incorrect plugin structure.
  fix Verify that your PostCSS plugin receives a valid `root` object and that the input CSS is not empty or malformed. Ensure your plugin adheres to the `postcssPlugin` structure.

Warnings

• breaking cssnano-utils, as a core component of cssnano, enforces strict Node.js engine requirements. Running with unsupported Node.js versions (e.g., older than 18.12.0) will lead to runtime errors or unexpected behavior.
  Fix: Ensure your project uses a Node.js version compatible with the 'engines' field: `^18.12.0 || ^20.9.0 || >=22.0`. Update Node.js or use a version manager like `nvm` to switch versions.
• gotcha cssnano-utils is tightly coupled with PostCSS and requires it as a peer dependency. Version mismatches between `postcss` and `cssnano-utils` (or the `cssnano` package it's part of) can lead to plugin loading failures, AST traversal errors, or incorrect CSS transformations.
  Fix: Always install `postcss` explicitly, ensuring its version satisfies the `cssnano-utils` peer dependency (`^8.4.32` for v5.x). When updating `cssnano`, also check the recommended `postcss` version.
• deprecated Direct manipulation of PostCSS AST nodes' `raws` properties for formatting can be brittle. `rawCache` plugin is provided to manage raw value formatting more robustly, but relying on internal `raws` for custom plugins can be problematic across PostCSS versions.
  Fix: Whenever possible, leverage the `rawCache` plugin for managing raw value integrity. If direct `raws` manipulation is necessary, thoroughly test against different PostCSS versions to ensure compatibility and stability.

Install

• npm install cssnano-utils npm
• yarn add cssnano-utils yarn
• pnpm add cssnano-utils pnpm

Imports

• rawCache
  wrong:

  const { rawCache } = require('cssnano-utils');

  correct:

  import { rawCache } from 'cssnano-utils';

  Primarily used as a PostCSS plugin for managing raw value formatting. Ships TypeScript types.
• getArguments
  wrong:

  import getArguments from 'cssnano-utils';

  correct:

  import { getArguments } from 'cssnano-utils';

  A named export utility function to parse CSS arguments, typically used internally by cssnano plugins.
• sameParent
  wrong:

  const sameParent = require('cssnano-utils').sameParent;

  correct:

  import { sameParent } from 'cssnano-utils';

  Another named export utility for checking relationships between PostCSS AST nodes.

Quickstart

Demonstrates the use of `getArguments` to parse CSS values and `rawCache` as a PostCSS plugin to manage AST node formatting.

import postcss from 'postcss';
import { rawCache, getArguments } from 'cssnano-utils';

async function processCssWithUtils(cssInput) {
  const myPlugin = (opts = {}) => {
    return {
      postcssPlugin: 'my-custom-plugin',
      Declaration(decl) {
        // Example using getArguments
        if (decl.prop === 'transform' && decl.value.includes('rotate')) {
          const args = getArguments(decl.value);
          console.log(`Arguments for transform: ${JSON.stringify(args)}`);
        }
      },
      // Example using rawCache as a PostCSS plugin
      OnceExit(root) {
        root.walkDecls('color', (decl) => {
          decl.value = 'red'; // Modify a value
        });
      }
    };
  };
  myPlugin.postcss = true;

  const result = await postcss([myPlugin(), rawCache()]).process(cssInput, { from: undefined });
  console.log('Processed CSS:\n', result.css);
  return result.css;
}

const sampleCss = `
h1 {
  color: green; /* original color */
  transform: rotate(30deg) scale(1.2, 0.5);
}
/* Example of a more complex rule */
@media screen and (min-width: 768px) {
  h1 {
    font-size: 24px;
  }
}
`;

processCssWithUtils(sampleCss);