css-what

library8.0.0jsnpmunverified

css-what is a robust and efficient JavaScript library designed for parsing CSS selectors into a structured, machine-readable format. It currently stands at version 8.0.0, which notably transitioned to an ESM-only distribution. The library's release cadence is somewhat irregular, with major versions introducing significant changes like ESM support and refinements to parsing logic. It provides a detailed tokenization of CSS selectors, representing elements, attributes, pseudos, and combinators as distinct objects with their respective properties. This detailed output makes it suitable for applications requiring granular analysis or manipulation of CSS selectors, such as styling engines, static analysis tools, or browser polyfills, differentiating it from simpler selector string processors by its deep structural representation.

serialization

npm install css-what

github ↗package ↗

INSTALL

IMPORT

SIG · CSS-WHAT

css-what

serializationjavascriptv8.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CSSwhat

✓ import * as CSSwhat from 'css-what';

✗ const CSSwhat = require('css-what');

Since v8.0.0, css-what is ESM-only and does not support CommonJS `require()` syntax. Use namespace import.

parse

✓ import { parse } from 'css-what';

✗ import { parse } from 'css-what/dist/index.js';

Prefer direct named imports for better tree-shaking and explicit dependency. No need to specify full path.

stringify

✓ import { stringify } from 'css-what';

Used to convert a parsed selector array back into a CSS string.

This quickstart demonstrates how to parse CSS selectors into a tokenized array and how to stringify them back to a CSS string, covering basic and compound selectors.

import * as CSSwhat from "css-what"; // Example 1: Basic selector parsing const selector1 = "div[data-id='123']:hover"; const parsedSelector1 = CSSwhat.parse(selector1); console.log(`Parsed '${selector1}':`); console.log(JSON.stringify(parsedSelector1, null, 2)); /* Expected output for selector1: [ [ { type: 'tag', name: 'div' }, { type: 'attribute', name: 'data-id', action: 'equals', value: '123', ignoreCase: null }, { type: 'pseudo', name: 'hover', data: null } ] ] */ // Example 2: Multiple selectors and stringification const selector2 = "a.link, #main > p"; const parsedSelector2 = CSSwhat.parse(selector2); console.log(`\nParsed '${selector2}':`); console.log(JSON.stringify(parsedSelector2, null, 2)); const stringifiedSelector2 = parsedSelector2.map(CSSwhat.stringify).join(", "); console.log(`\nStringified back to: '${stringifiedSelector2}'`); // Expected output: "a.link, #main > p"

Debug

Known issues

breakingcss-what versions 8.0.0 and above are ESM-only, removing CommonJS support. This means `require()` statements will no longer work.

fix

Migrate all import statements from `const pkg = require('pkg');` to `import * as pkg from 'pkg';` or `import { symbol } from 'pkg';`. Ensure your project is configured for ESM.

affects: >=8.0.0

breakingIn css-what v6.0.0, all options were removed from the `parse` function, simplifying its API. Code relying on an `options` object will fail.

fix

Refactor code to no longer pass an `options` object as a second argument to `CSSwhat.parse()`.

affects: >=6.0.0

breakingcss-what v6.0.0 changed the default behavior of `ignoreCase`, and tags/attributes are no longer lowercased by default. Additionally, v5.0.0 introduced `ignoreCase` changes related to the `s` flag and HTML spec defaults, which could affect existing parsing logic.

fix

Review code that relies on specific casing behavior for tags and attributes, or on the default `ignoreCase` logic. Adjust expectations or implement manual casing/case-insensitivity if required by your application.

affects: >=5.0.0

gotchaVersions `6.2.0` and `6.2.1` of `css-what` contained breaking changes or regressions that were deemed unstable. Version `6.2.2` was released as a re-publish of `6.1.0` to revert these changes.

fix

Avoid `css-what` versions `6.2.0` and `6.2.1`. Prefer `6.1.0` or `6.2.2` if you need features from that range, or upgrade to a newer major version.

affects: 6.2.0, 6.2.1

breakingWhile v6.0.0 still provided CommonJS, the introduction of ES6 module exports in this version could cause build system issues due to resolution conflicts or changes in how bundlers handle dual packages, even before the full ESM-only transition in v8.

fix

If encountering build errors, explicitly configure your bundler (e.g., Webpack, Rollup) to prefer CJS or ESM resolution, or upgrade to v8.0.0 which is pure ESM.

affects: >=6.0.0 <8.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module ... not supported.

Attempting to use `require()` to import `css-what` in a project configured for ESM, or when using version 8.0.0 or later which is ESM-only.

fix

Change `const CSSwhat = require("css-what");` to `import * as CSSwhat from "css-what";` or `import { parse, stringify } from "css-what";`. Ensure your `package.json` specifies `"type": "module"` if applicable, or use a bundler correctly configured for ESM.

TypeError: CSSwhat.parse is not a function

This usually occurs if `css-what` was imported as a default export (`import CSSwhat from 'css-what';`) when it primarily exposes named or namespace exports.

fix

Use a namespace import: `import * as CSSwhat from 'css-what';` then access functions like `CSSwhat.parse()`. Alternatively, use named imports directly: `import { parse, stringify } from 'css-what';`.

TypeError: CSSwhat.parse(...) is not valid JSON

This error is not specific to `css-what` but might arise if the parsed output is incorrectly handled, for example, if a developer expects a string instead of the array of tokens that `parse` returns, and tries to `JSON.parse` it.

fix

The `CSSwhat.parse()` function returns a two-dimensional array of token objects. Ensure your code correctly iterates over this array structure, as shown in the quickstart example, rather than attempting to `JSON.parse` the raw output.

Upgrade

Version history

8.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/fb55/css-what ↗

packagehttps://www.npmjs.com/package/css-what ↗