{"id":10697,"library":"csscomb-core","title":"CSScomb Core","description":"CSScomb Core is a foundational framework designed for building custom CSS postprocessors. It provides a robust set of features, including a powerful parser that supports various CSS preprocessor syntaxes (CSS, Less, Sass, SCSS), an API for defining and managing processing options, and utilities for applying these processes to files, directories, or strings. The current stable version, 3.0.6, continues to focus on providing a modular and extensible architecture for linting and transforming CSS code programmatically. Its key differentiators lie in its flexible plugin system, allowing developers to create highly specific styling rules and formatting logic, and its ability to handle different CSS-like syntaxes through a unified interface. While a specific release cadence isn't published, it appears to be maintained as a core component for CSS processing tasks.","status":"active","version":"3.0.6","language":"javascript","source_language":"en","source_url":"https://github.com/csscomb/core","tags":["javascript"],"install":[{"cmd":"npm install csscomb-core","lang":"bash","label":"npm"},{"cmd":"yarn add csscomb-core","lang":"bash","label":"yarn"},{"cmd":"pnpm add csscomb-core","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"CSScomb Core v3.x is primarily a CommonJS package. Direct ESM `import` statements may require specific Node.js loader configurations or bundler setups for correct interoperation.","wrong":"import Comb from 'csscomb-core';","symbol":"Comb","correct":"const Comb = require('csscomb-core');"}],"quickstart":{"code":"const Comb = require('csscomb-core');\nconst fs = require('fs');\nconst path = require('path');\n\nasync function processCssString() {\n  // Define a configuration object. In a real application, this would typically\n  // be loaded from a .csscomb.json file or similar.\n  const config = {\n    'always-semicolon': true,\n    'color-case': 'lower',\n    'leading-zero': false,\n    'space-before-colon': 'zero',\n    'space-after-colon': 'one',\n    'selector-separator-newline': true\n  };\n\n  // Instantiate the Comb processor. The first parameter is typically an array\n  // of plugin instances if you're dynamically loading them, or an empty array.\n  // The second parameter specifies the default syntax.\n  const comb = new Comb([], 'css');\n\n  // Load the desired configuration into the comb instance.\n  comb.configure(config);\n\n  const rawCss = `\n    .my-class {\n      color: #FF0000;\n      font-size: 16px\n    }\n    a {display :block ;  padding: 10px}\n    div{border: 1px solid #CCC;}\n  `;\n\n  try {\n    console.log('Original CSS:\\n', rawCss);\n    \n    // Process the string, applying the configured rules.\n    const processedCss = await comb.processString(rawCss, { filename: 'example.css', syntax: 'css' });\n    console.log('\\nProcessed CSS:\\n', processedCss);\n\n    // You can also lint the string to find issues without modifying it.\n    const lintErrors = await comb.lintString(rawCss, { filename: 'example.css', syntax: 'css' });\n    if (lintErrors.length > 0) {\n      console.log('\\nLinting Errors Found:');\n      lintErrors.forEach(error => console.log(`- [${error.line}:${error.column}] ${error.message}`));\n    } else {\n      console.log('\\nNo linting errors found.');\n    }\n\n  } catch (error) {\n    console.error('Error processing CSS:', error);\n  }\n}\n\nprocessCssString();","lang":"javascript","description":"Demonstrates how to import CSScomb Core, configure it with rules, and then use it to process and lint a CSS string asynchronously."},"warnings":[{"fix":"Always use `const Comb = require('csscomb-core');` for reliable integration in both CommonJS and environments that support CJS interop.","message":"The package primarily documents and supports CommonJS `require()` syntax. While Node.js has ESM support, directly using `import Comb from 'csscomb-core'` might lead to unexpected behavior or require specific Node.js loader configurations, especially in older environments or bundlers not configured for CJS interop.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Always use `await` with these methods within an `async` function, or chain `.then()` and `.catch()` handlers explicitly to manage asynchronous operations.","message":"All core processing and linting methods (`processString`, `lintFile`, `processDirectory`, etc.) return Promises. Failing to `await` these calls or handle their resolutions can lead to `UnhandledPromiseRejectionWarning` or incorrect program flow where subsequent operations execute before processing is complete.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"For clearer configuration management, it's recommended to instantiate with `new Comb([], syntax)` and then load your configuration explicitly using `comb.configure(yourConfigObject)`.","message":"The `new Comb(options, syntax)` constructor's `options` parameter is for an array of plugin instances or an initial configuration object, which can be confusing given the separate `comb.configure(config)` method. Misunderstanding this parameter's purpose can lead to an unconfigured or improperly initialized processor instance.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Ensure the `syntax` parameter is one of the explicitly supported values ('css', 'less', 'sass', 'scss') and accurately matches the input content being processed.","message":"CSScomb Core's parsing and processing are highly dependent on the specified `syntax` (e.g., 'css', 'less', 'sass', 'scss'). Providing an unsupported or incorrect syntax string to the constructor or the `processString`/`lintString` options will result in parsing failures or unexpected output.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `const Comb = require('csscomb-core');` is correctly placed and use `new Comb([], 'css');` to create an instance.","cause":"Attempting to call `Comb` as a constructor without using the `new` keyword, or if `require('csscomb-core')` did not correctly return the constructor function.","error":"TypeError: Comb is not a constructor"},{"fix":"Verify the `Comb` import and instance creation: `const comb = new Comb([], 'css');`.","cause":"The `comb` instance was not created successfully, or the `Comb` object itself was not correctly imported/required, leading to `comb` being undefined or not the expected instance.","error":"TypeError: comb.processString is not a function"},{"fix":"Add `await` before the promise-returning call, or handle the Promise explicitly: `await comb.processString(...)` or `comb.processString(...).then(...).catch(...)`.","cause":"An asynchronous method like `processString` or `lintFile` was called without `await` in an `async` context, or without `.then()` and `.catch()` handlers to explicitly manage its resolution.","error":"UnhandledPromiseRejectionWarning: Promise { <pending> }"},{"fix":"Use one of the officially supported syntaxes: `'css'`, `'less'`, `'sass'`, or `'scss'`.","cause":"An unrecognized or unsupported string was passed as the `syntax` parameter to the `Comb` constructor or within the options object for `processString`/`lintString`.","error":"Error: Syntax 'invalid' is not supported"}],"ecosystem":"npm"}