@timkit/css-parser

CSS Parser

A high-performance, character-by-character CSS parser that converts CSS to JavaScript objects and vice versa.

Features

• Parse CSS strings to JavaScript objects
• Stringify JavaScript objects back to CSS
• Character by character parsing for high performance
• Support for complex selectors and @-rules
• Handle comments and nested structures
• Optional output compression

Installation

# If the package is published on npm
npm install @timkit/css-parser

# Or install directly from GitHub
npm install github:timkit-dev/css-parser

Usage

Parsing CSS to JavaScript

import { parse } from '@timkit/css-parser';

const css = `
.container {
  width: 100px;
  height: 200px;
}

.button {
  background-color: #ff0000;
}
`;

const cssObject = parse(css);
console.log(JSON.stringify(cssObject, null, 2));

Output:

{
  "rules": [
    {
      "selector": ".container",
      "declarations": [
        {
          "property": "width",
          "value": "100px"
        },
        {
          "property": "height",
          "value": "200px"
        }
      ]
    },
    {
      "selector": ".button",
      "declarations": [
        {
          "property": "background-color",
          "value": "#ff0000"
        }
      ]
    }
  ],
  "atRules": []
}

Converting JavaScript to CSS

import { stringify } from '@timkit/css-parser';

const cssObject = {
  rules: [
    {
      selector: '.container',
      declarations: [
        { property: 'width', value: '100px' },
        { property: 'height', value: '200px' }
      ]
    },
    {
      selector: '.button',
      declarations: [
        { property: 'background-color', value: '#ff0000' }
      ]
    }
  ]
};

const css = stringify(cssObject);
console.log(css);

Output:

.container {
  width: 100px;
  height: 200px;
}

.button {
  background-color: #ff0000;
}

Compressed Output

import { stringify } from '@timkit/css-parser';

const cssObject = {
  rules: [
    {
      selector: '.container',
      declarations: [
        { property: 'width', value: '100px' },
        { property: 'height', value: '200px' }
      ]
    },
    {
      selector: '.button',
      declarations: [
        { property: 'background-color', value: '#ff0000' }
      ]
    }
  ]
};

const css = stringify(cssObject, { compress: true });
console.log(css);

Output:

.container{width:100px;height:200px;}.button{background-color:#ff0000;}

Working with @-rules

The parser supports various @-rules like @media, @keyframes, @import, etc.

import { parse, stringify } from '@timkit/css-parser';

const css = `
@media (max-width: 768px) {
  .container {
    width: 100%;
  }
}

@keyframes fadeIn {
  0% { opacity: 0; }
  100% { opacity: 1; }
}

@import url('styles.css');
`;

const cssObject = parse(css);
console.log(JSON.stringify(cssObject, null, 2));

// Convert back to CSS
const regeneratedCss = stringify(cssObject);
console.log(regeneratedCss);

Parser Capabilities and Limitations

Supported Features

• Standard CSS rules with selectors and declarations
• Complex selectors (including pseudo-classes, attributes, etc.)
• @-rules (@media, @keyframes, @import, @font-face, etc.)
• Nested @-rules (e.g., @supports inside @media)
• Comments (both inline and block)
• Various property values including functions, strings, and units

Limitations

• Does not validate CSS syntax beyond basic structure
• Limited support for some complex CSS4 features
• May not handle all edge cases in extremely complex selectors
• Error recovery is basic; malformed input may result in incomplete parsing

Running Tests

npm test

License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.

Copyright 2025 timkit.dev

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.