Registry / serialization / shady-css-parser

shady-css-parser

library0.1.0jsnpmunverified

Shady CSS Parser is a JavaScript library designed for fast, small, and flexible runtime parsing and transformation of CSS. It is currently in an early development stage, with the latest stable version being 0.1.0. While it is not fully spec-compliant, it is designed to parse all spec-compliant CSS loosely and efficiently, prioritizing graceful error recovery to handle malformed CSS in a manner similar to browsers. This makes it particularly suitable for scenarios requiring runtime manipulation, such as in tools like Polymer or Polymer Designer. The library ships with TypeScript types and focuses on providing a performant parsing and stringification mechanism, though it notably discards most insignificant whitespace during processing. Its release cadence appears to be iterative with frequent minor updates as indicated by the 0.0.x version progression.

serialization web-framework

npm install shady-css-parser

github ↗package ↗

INSTALL

IMPORT

SIG · SHADY-CSS-PARSER

shady-css-parser

serializationjavascriptv0.1.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.

Parser

✓ import { Parser } from 'shady-css-parser';

✗ const Parser = require('shady-css-parser').Parser;

Primary class for parsing CSS. The library is ESM-first; CommonJS `require` is not the idiomatic approach.

Stringifier

✓ import { Stringifier } from 'shady-css-parser';

✗ import ShadyCss from 'shady-css-parser'; const stringifier = new ShadyCss.Stringifier();

Primary class for converting an AST back to CSS. All core components are named exports.

NodeFactory

✓ import { NodeFactory } from 'shady-css-parser';

✗ import * as shadyCss from 'shady-css-parser'; const factory = new shadyCss.default.NodeFactory();

Used for extending parser behavior with custom node types. Access as a named export.

* as shadyCss

✓ import * as shadyCss from 'shady-css-parser';

✗ const shadyCss = require('shady-css-parser');

Common pattern to import all named exports into a namespace object. Still requires an ESM environment.

Demonstrates the basic usage of Shady CSS Parser to parse a CSS string into an AST and then stringify the AST back into a normalized CSS string.

import { Parser, Stringifier } from 'shady-css-parser'; const cssInput = ` body { color: red; font-size: 16px; /* Custom property example */ --main-bg: blue; } .container { padding: 10px; border: 1px solid black; } `; // Initialize the Parser and parse the CSS string into an Abstract Syntax Tree (AST). const parser = new Parser(); const ast = parser.parse(cssInput); console.log('--- Parsed AST (truncated for brevity) ---'); console.log(JSON.stringify(ast, null, 2).substring(0, 500) + '...\n'); // Log a portion of the AST // Initialize the Stringifier and convert the AST back into a CSS string. const stringifier = new Stringifier(); const outputCss = stringifier.stringify(ast); console.log('--- Stringified CSS ---'); console.log(outputCss); /* Output will be normalized, and most insignificant whitespace will be discarded. For example: body {color: red; font-size: 16px; --main-bg: blue;} .container {padding: 10px; border: 1px solid black;} */

Debug

Known issues

breakingThe `Tokenizer` class underwent an API change where the method `findNextToken` was renamed to `getNextToken`.

fix

If you are extending or directly using the `Tokenizer` for custom parsing, update calls from `findNextToken()` to `getNextToken()`.

affects: >=0.0.6

gotchaThis parser is explicitly designed for loose and flexible parsing, not strict spec compliance. While it aims to parse all spec-compliant CSS, its error recovery and handling of malformed CSS may differ from strict CSS specification parsers.

fix

Be aware that the AST or stringified output might not perfectly match highly malformed CSS inputs compared to a strict parser. Test thoroughly if strict spec adherence is critical.

affects: *

gotchaThe built-in `Parser` and `Stringifier` intentionally discard most insignificant whitespace from parsed CSS. This means a round-trip (parse then stringify) will not preserve original formatting.

fix

Do not rely on whitespace preservation when using the default stringifier. If exact whitespace preservation is required, custom stringification logic would be necessary, potentially requiring modifications to the AST during parsing to retain whitespace information.

affects: *

gotchaThe package is currently at version 0.1.0, indicating an early development stage. APIs may change frequently and without strict adherence to semantic versioning until a 1.0.0 release.

fix

Pin exact versions in your `package.json` (e.g., `"shady-css-parser": "0.1.0"`) and carefully review changelogs for any breaking changes when upgrading.

affects: <1.0.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Attempting to use ES module `import` syntax in a CommonJS Node.js environment or in an un-transpiled browser environment.

fix

Ensure your Node.js project's `package.json` contains `"type": "module"` or use a bundler (like Webpack, Rollup) or transpiler (like Babel, TypeScript) for browser or older Node.js environments. Alternatively, manually configure Node to treat files as ESM.

TypeError: shadyCss.Parser is not a constructor

Trying to instantiate `Parser` (or other named exports) from a CommonJS `require` call that doesn't correctly destructure or from an incorrect default import in ESM.

fix

Use a named import: `import { Parser } from 'shady-css-parser';` for ESM. If strictly using CommonJS (not recommended for this library), ensure `const { Parser } = require('shady-css-parser');`.

Error: Cannot find module 'shady-css-parser'

The `shady-css-parser` package has not been installed, or there's a typo in the package name or import path.

fix

Run `npm install shady-css-parser` or `yarn add shady-css-parser` in your project directory. Double-check the spelling of the package name in your `package.json` and import statements.

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Bingbot

Resources

githubhttps://github.com/PolymerLabs/shady-css-parser ↗

packagehttps://www.npmjs.com/package/shady-css-parser ↗