{"id":10698,"library":"cssnano-utils","title":"cssnano Utilities","description":"cssnano-utils is a foundational library providing essential utility methods and a PostCSS plugin specifically designed for use within the cssnano ecosystem. It offers functionalities like `rawCache` for managing raw value formatting of AST nodes, `getArguments` for parsing CSS function arguments, and `sameParent` for checking node relationships within the PostCSS AST. Currently at version 5.0.1, this package does not have an independent release cadence but updates in tandem with its parent project, cssnano, which sees frequent bug fix and minor releases (e.g., v7.1.5, v7.1.4, v7.1.3 within a short timeframe). Its key differentiator is its specialized nature, providing low-level, performance-optimized utilities that are integral to how cssnano plugins analyze and transform CSS, rather than being a standalone CSS processing tool.","status":"active","version":"5.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/cssnano/cssnano","tags":["javascript","typescript"],"install":[{"cmd":"npm install cssnano-utils","lang":"bash","label":"npm"},{"cmd":"yarn add cssnano-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add cssnano-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for AST manipulation and plugin integration.","package":"postcss","optional":false}],"imports":[{"note":"Primarily used as a PostCSS plugin for managing raw value formatting. Ships TypeScript types.","wrong":"const { rawCache } = require('cssnano-utils');","symbol":"rawCache","correct":"import { rawCache } from 'cssnano-utils';"},{"note":"A named export utility function to parse CSS arguments, typically used internally by cssnano plugins.","wrong":"import getArguments from 'cssnano-utils';","symbol":"getArguments","correct":"import { getArguments } from 'cssnano-utils';"},{"note":"Another named export utility for checking relationships between PostCSS AST nodes.","wrong":"const sameParent = require('cssnano-utils').sameParent;","symbol":"sameParent","correct":"import { sameParent } from 'cssnano-utils';"}],"quickstart":{"code":"import postcss from 'postcss';\nimport { rawCache, getArguments } from 'cssnano-utils';\n\nasync function processCssWithUtils(cssInput) {\n  const myPlugin = (opts = {}) => {\n    return {\n      postcssPlugin: 'my-custom-plugin',\n      Declaration(decl) {\n        // Example using getArguments\n        if (decl.prop === 'transform' && decl.value.includes('rotate')) {\n          const args = getArguments(decl.value);\n          console.log(`Arguments for transform: ${JSON.stringify(args)}`);\n        }\n      },\n      // Example using rawCache as a PostCSS plugin\n      OnceExit(root) {\n        root.walkDecls('color', (decl) => {\n          decl.value = 'red'; // Modify a value\n        });\n      }\n    };\n  };\n  myPlugin.postcss = true;\n\n  const result = await postcss([myPlugin(), rawCache()]).process(cssInput, { from: undefined });\n  console.log('Processed CSS:\\n', result.css);\n  return result.css;\n}\n\nconst sampleCss = `\nh1 {\n  color: green; /* original color */\n  transform: rotate(30deg) scale(1.2, 0.5);\n}\n/* Example of a more complex rule */\n@media screen and (min-width: 768px) {\n  h1 {\n    font-size: 24px;\n  }\n}\n`;\n\nprocessCssWithUtils(sampleCss);\n","lang":"typescript","description":"Demonstrates the use of `getArguments` to parse CSS values and `rawCache` as a PostCSS plugin to manage AST node formatting."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<5.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `import { rawCache } from 'cssnano-utils';` is used and `rawCache()` is included in the `postcss` plugin array: `postcss([rawCache()])`.","cause":"The PostCSS plugin provided by `cssnano-utils` (e.g., `rawCache`) was not correctly imported or passed to PostCSS.","error":"Error: PostCSS plugin <plugin-name> was not found"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'walkDecls')"}],"ecosystem":"npm"}