React Standard Tree CSS Selector Parser

2.2.3 · maintenance · verified Tue Apr 21

rst-selector-parser is a JavaScript library designed for parsing CSS-like selectors specifically within the context of React Standard Trees (RST). It provides utilities to parse a CSS selector string into an Abstract Syntax Tree (AST) representing the selector's structure, and conversely, to generate a selector string from such an AST. This package is frequently utilized in conjunction with testing libraries like Enzyme for traversing and querying rendered React components. Currently at version 2.2.3, it is a fork of the `scalpel` library, adapted and optimized for the RST environment, ensuring compatibility with its unique traversal needs. Its primary differentiation lies in this specialized focus, offering a robust and programmatic way to interact with component trees using familiar CSS selector syntax, which can be particularly beneficial for testing and introspection workflows in React applications. The last significant update was in late 2019, suggesting a mature but slow-moving maintenance phase.

Common errors

```
Syntax Error: Unexpected token '<token_type>' (at <line>:<column>)
```
cause The CSS selector string provided to `parser.parse()` contains invalid syntax or characters not supported by the parser's interpretation of W3C CSS3 Selectors.

fix Review the selector string for typos, incorrect combinators, or malformed attributes/pseudo-classes. Consult the W3C CSS3 Selectors specification and the library's `Token types` documentation for supported syntax.
```
TypeError: Cannot destructure property 'createParser' of 'require(...)' as it is undefined.
```
cause This error typically occurs when attempting to use a CommonJS `require()` statement in an environment that expects ESM, or when trying to access named exports incorrectly from a module that primarily exports as a default.

fix If using an ESM context (e.g., `type: 'module'` in `package.json`), use `import { createParser } from 'rst-selector-parser';`. If explicitly using CommonJS, ensure the `require` statement correctly destructures the named export: `const { createParser } = require('rst-selector-parser');`.

Warnings

gotcha This library is specifically designed for parsing selectors within a React Standard Tree (RST) context, commonly used with Enzyme. It is not a general-purpose CSS parser for browser DOM or arbitrary HTML. Attempting to use it for non-RST parsing may lead to unexpected behavior or unsupported selector types.
Fix: Ensure you are using this parser in the intended React testing or RST traversal context. For general DOM/HTML CSS parsing, use a dedicated browser or Node.js DOM parser.
maintenance The package has not seen significant updates or new releases since December 2019 (version 2.2.3). While functional, it indicates a maintenance-only status. Users requiring support for newer CSS selector specifications or active development might find it lacking.
Fix: Be aware that new features or bug fixes beyond critical issues are unlikely. If you require advanced or very recent CSS selector features, consider alternative, more actively maintained parsing solutions.
gotcha The package uses CommonJS for its 'main' entry point and ESM for 'module'. Incorrectly mixing `require()` with ESM-style imports for named exports, or vice-versa, can lead to undefined exports or runtime errors depending on your build setup and Node.js version.
Fix: For ESM projects, stick to `import { name } from 'pkg';`. For CommonJS projects, use `const { name } = require('pkg');`. Ensure your build tools (e.g., Webpack, Rollup) are configured correctly to handle dual packages.

Install

npm install rst-selector-parser npm
yarn add rst-selector-parser yarn
pnpm add rst-selector-parser pnpm

Imports

createParser
wrong:
```
const createParser = require('rst-selector-parser');
```
correct:
```
import { createParser } from 'rst-selector-parser';
```
Use named imports for ESM. For CommonJS, use `const { createParser } = require('rst-selector-parser');`
createGenerator
wrong:
```
import createGenerator from 'rst-selector-parser';
```
correct:
```
import { createGenerator } from 'rst-selector-parser';
```
Use named imports for ESM. For CommonJS, use `const { createGenerator } = require('rst-selector-parser');`. Avoid default imports.

Quickstart

Demonstrates parsing a CSS selector into a tokenized AST and then generating a selector string back from the AST.

import { createGenerator, createParser } from 'rst-selector-parser';

const parser = createParser();
const generator = createGenerator();

// Parse a CSS selector string into an AST
const tokens = parser.parse('.foo.bar');
console.log('Parsed Tokens:', JSON.stringify(tokens, null, 2));
/*
[
  {
    "type": "selector",
    "body": [
      {
        "type": "classSelector",
        "name": "foo"
      },
      {
        "type": "classSelector",
        "name": "bar"
      }
    ]
  }
]
*/

// Generate a selector string from the AST
const selector = generator.generate(tokens[0]);
console.log('Generated Selector:', selector);
// .foo.bar

view raw JSON →