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

``bash


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

$3

`typescript
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:

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

$3

`typescript
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:

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

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

$3

`typescript
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:

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

$3

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

`typescript
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

$3

- 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

$3

- 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

`bash
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.