Registry / serialization / cssom

cssom

JSON →
library0.5.0jsnpmunverified

CSSOM.js is a pure JavaScript CSS parser and a partial implementation of the W3C CSS Object Model (CSSOM). Currently at version 0.5.0, this library provides functionality to parse raw CSS strings into a structured object representation, allowing for basic programmatic inspection and manipulation of CSS rules. Its release cadence has been slow, with the last publish being 5 years ago. A key differentiator is its direct representation of CSS as a JavaScript object. However, it explicitly advises against its use for advanced CSS processing tasks such as minification, munging, or reformatting, particularly where the preservation of property order or fallback declarations (e.g., `background: gray; background: linear-gradient(...)`) is critical, as it applies CSS cascade rules and overwrites properties. It also has known limitations, including incomplete support for all CSS escape sequences and incompatibility with Internet Explorer versions prior to 9.

serializationweb-framework
npm install cssom
github ↗package ↗
INSTALL
IMPORT
SIG · CSSOM
C
cssom
serializationjavascriptv0.5.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.

CSSOM
✓ const CSSOM = require('cssom');
✗ import CSSOM from 'cssom';
The `cssom` package is primarily a CommonJS module for Node.js environments. For browser usage, a global `CSSOM` variable is exposed after running the `build.js` script and including the resulting file. Direct ESM imports are not officially supported.
parse
✓ const CSSOM = require('cssom'); const parsedCSS = CSSOM.parse('body {color: black;}');
✗ import { parse } from 'cssom';
The `parse` function is a method of the main `CSSOM` object, not a named export. Attempting to destructure it directly will result in an error as it's not a standalone function.
CSSStyleDeclaration
✓ const CSSOM = require('cssom'); const styleDeclaration = new CSSOM.CSSStyleDeclaration();
✗ import { CSSStyleDeclaration } from 'cssom';
Like `parse`, `CSSStyleDeclaration` (and other CSSOM interfaces) are properties of the main `CSSOM` object. They are not individually exported for direct named imports.

This quickstart demonstrates how to parse a CSS string using `CSSOM.parse()` in Node.js and iterate through the resulting CSS rules and their styles, highlighting the property overwriting behavior.

const CSSOM = require('cssom'); const cssString = ` body { font-family: Arial, sans-serif; color: #333; } .container { width: 960px; margin: 0 auto; padding: 20px; background: #f0f0f0; /* This will be overwritten */ background: linear-gradient(to bottom, white 0%, black 100%); } `; const stylesheet = CSSOM.parse(cssString); console.log('Parsed CSS Rules:'); stylesheet.cssRules.forEach(rule => { if (rule.selectorText) { console.log(`Selector: ${rule.selectorText}`); for (let i = 0; i < rule.style.length; i++) { const prop = rule.style[i]; console.log(` ${prop}: ${rule.style[prop]}`); } } }); // Demonstrating the property overwriting issue const containerRule = stylesheet.cssRules.find(r => r.selectorText === '.container'); if (containerRule) { console.log('\nProperties for .container after parsing:'); // Note: Only the last 'background' property will be present due to cascading logic. console.log(` background: ${containerRule.style.background}`); }
Debug
Known issues
gotchaCSSOM applies standard CSS cascade logic, which means that if multiple declarations for the same property exist within a single rule (e.g., fallback `background` values), only the last one will be preserved in the parsed output, overwriting previous declarations. This makes it unsuitable for tools requiring preservation of such fallbacks.
fix
For CSS minification, munging, or reformatting where property order and all declarations must be preserved, consider using purpose-built tools like PostCSS, ReworkCSS, CSSTree, or CSSToJSON.
affects: >=0.1.0
gotchaThe library has limited support for CSS escape sequences. While `\'` and `\"` are allowed, full CSS escape sequence handling is not implemented.
fix
Preprocess CSS to normalize or resolve complex escape sequences before feeding them into CSSOM, or handle them manually in post-processing of the parsed output.
affects: >=0.3.0
gotchaCSSOM.js does not work in Internet Explorer versions prior to IE9 due to its reliance on unsupported getters/setters in those older browsers.
fix
Ensure that the target browser environment is IE9+ if using CSSOM on the client-side. For broader compatibility, consider alternative client-side CSS parsers or polyfills for the necessary JavaScript features.
affects: <0.5.0
deprecatedThe GitHub repository README for CSSOM explicitly states that the project is 'Unmaintained!'. While the npm package is still available, active development and issue resolution are not ongoing, with the last publish being 5 years ago.
fix
Evaluate the long-term viability for new projects. For ongoing development or critical applications, consider modern, actively maintained alternatives like PostCSS or the browser's native CSS Typed OM (where supported).
affects: >=0.5.0
Errors
Common errors & fixes
ReferenceError: CSSOM is not defined
Attempting to use `CSSOM` in a Node.js environment without `require('cssom')`, or in a browser without including the `build/CSSOM.js` file generated by the build process.
fix
For Node.js, add `const CSSOM = require('cssom');` at the top of your file. For browser use, run `node build.js` in the project directory and then include the generated `build/CSSOM.js` file in your HTML using a `<script>` tag.
TypeError: CSSOM.parse is not a function
This error typically occurs if you try to import `parse` as a named export (`import { parse } from 'cssom'`) or if `require('cssom')` does not return the expected `CSSOM` object. The `parse` method is a property of the main `CSSOM` object.
fix
Ensure you import the entire `CSSOM` object using `const CSSOM = require('cssom');` and then call `CSSOM.parse(...)`.
Unexpected parsing result: CSS property values are overwritten or missing.
CSSOM's parser applies standard CSS cascading rules, which results in duplicate properties within a single rule (e.g., `background: gray; background: linear-gradient(...)`) being overwritten, with only the last valid declaration being preserved.
fix
If your use case requires preserving all declarations, including fallbacks or duplicate properties, CSSOM is not the right tool. Consider using alternative CSS parsers like PostCSS or reworkcss/css, which offer more granular control over parsing and AST manipulation.
Upgrade
Version history
0.5.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
17 hits · last 30 days
node
12
Amazon
1
Resources
githubhttps://github.com/NV/CSSOM ↗
packagehttps://www.npmjs.com/package/cssom ↗
cssom — npm install cssom · libregistry