CSScomb Core

Common errors

• TypeError: Comb is not a constructor

  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.
  fix Ensure `const Comb = require('csscomb-core');` is correctly placed and use `new Comb([], 'css');` to create an instance.

• TypeError: comb.processString is not a function

  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.
  fix Verify the `Comb` import and instance creation: `const comb = new Comb([], 'css');`.

• UnhandledPromiseRejectionWarning: Promise { <pending> }

  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.
  fix Add `await` before the promise-returning call, or handle the Promise explicitly: `await comb.processString(...)` or `comb.processString(...).then(...).catch(...)`.

• Error: Syntax 'invalid' is not supported

  cause An unrecognized or unsupported string was passed as the `syntax` parameter to the `Comb` constructor or within the options object for `processString`/`lintString`.
  fix Use one of the officially supported syntaxes: `'css'`, `'less'`, `'sass'`, or `'scss'`.

Warnings

• gotcha 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.
  Fix: Always use `const Comb = require('csscomb-core');` for reliable integration in both CommonJS and environments that support CJS interop.
• gotcha 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.
  Fix: Always use `await` with these methods within an `async` function, or chain `.then()` and `.catch()` handlers explicitly to manage asynchronous operations.
• gotcha 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.
  Fix: For clearer configuration management, it's recommended to instantiate with `new Comb([], syntax)` and then load your configuration explicitly using `comb.configure(yourConfigObject)`.
• gotcha 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.
  Fix: Ensure the `syntax` parameter is one of the explicitly supported values ('css', 'less', 'sass', 'scss') and accurately matches the input content being processed.

Install

• npm install csscomb-core npm
• yarn add csscomb-core yarn
• pnpm add csscomb-core pnpm

Imports

• Comb
  wrong:

  import Comb from 'csscomb-core';

  correct:

  const Comb = require('csscomb-core');

  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.

Quickstart

Demonstrates how to import CSScomb Core, configure it with rules, and then use it to process and lint a CSS string asynchronously.

const Comb = require('csscomb-core');
const fs = require('fs');
const path = require('path');

async function processCssString() {
  // Define a configuration object. In a real application, this would typically
  // be loaded from a .csscomb.json file or similar.
  const config = {
    'always-semicolon': true,
    'color-case': 'lower',
    'leading-zero': false,
    'space-before-colon': 'zero',
    'space-after-colon': 'one',
    'selector-separator-newline': true
  };

  // Instantiate the Comb processor. The first parameter is typically an array
  // of plugin instances if you're dynamically loading them, or an empty array.
  // The second parameter specifies the default syntax.
  const comb = new Comb([], 'css');

  // Load the desired configuration into the comb instance.
  comb.configure(config);

  const rawCss = `
    .my-class {
      color: #FF0000;
      font-size: 16px
    }
    a {display :block ;  padding: 10px}
    div{border: 1px solid #CCC;}
  `;

  try {
    console.log('Original CSS:\n', rawCss);
    
    // Process the string, applying the configured rules.
    const processedCss = await comb.processString(rawCss, { filename: 'example.css', syntax: 'css' });
    console.log('\nProcessed CSS:\n', processedCss);

    // You can also lint the string to find issues without modifying it.
    const lintErrors = await comb.lintString(rawCss, { filename: 'example.css', syntax: 'css' });
    if (lintErrors.length > 0) {
      console.log('\nLinting Errors Found:');
      lintErrors.forEach(error => console.log(`- [${error.line}:${error.column}] ${error.message}`));
    } else {
      console.log('\nNo linting errors found.');
    }

  } catch (error) {
    console.error('Error processing CSS:', error);
  }
}

processCssString();