Getting Started

To get started simply grab the package from NPM

npm i lostra-cssParser

And import the functions you wish to use:

import {parseCss, stringify} from 'lostra-cssParser'

How to use

The package has two exported functions called parseCss and stringify.

Passing any valid CSS String to the parseCss function will turn it into an object (including the comments) for easier iteration and editing.

The parser handles @font-face rules correctly, but it can run into issues with @media queries!

const MyCSS = await fetch('https://cdnjs.cloudflare.com/ajax/libs/materialize/1.0.0/css/materialize.min.css');
let MyCSSObject = parseCss(await MyCss.text());

This outputs an object similar to below:

{
    selector: '@font-face',
    style: {
      'font-family': "'Oswald'",
      'font-style': 'normal',
      'font-weight': '400',
      src: "url(https://fonts.gstatic.com/s/oswald/v41/TK3_WkUHHAIjg75cFRf3bXL8LICs1_FvsUtiZTaR.woff2) format('woff2')",
      'unicode-range': 'U+0460-052F, U+1C80-1C88, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F'
    },
    comment: 'cyrillic-ext'
  }

You can then access and edit any properties you'd like. When you are done, simply stringify the CSS Object back via:

let MyCSSString = stringify(MyCSSObject);

which outputs a regular string that you can write to a file via fs.

@font-face{
 font-family: 'Oswald';
 font-style: normal;
 font-weight: 400;
 src: url(/public/assets/fonts/Oswald/Oswald_0.woff2) format('woff2');
 unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}

How it works

The parser implements a Tokenizer via RegEx and splits up the string based on specific delimiters such as comment blocks /* */, curly brackets etc.

The stringifier essentially merges the keys and values of the object back together, breaking the lines and tabbing at specific characters, such as curly brackets and semicolons, then it outputs a regular string value.

Performance

The component is used in astro-fonts to parse the downloaded CSS from GoogleFonts. The parser takes the URLs to the actual font assets, then an async function downloads said font assets. Then the object is changed to include the new paths for the local files instead of the original remote ones. This object is then stringified back to a CSS and saved to a CSS file via node:fs.

In astro-fonts the whole process of downloading 15 fonts, each with 4 weights, parsing the CSS, editing the entries, and writing it back to a file takes between 250-550ms in dev mode (time depends on Google here mostly.).

Downloading the Materialize CSS via CDN (the non-minified version), the download itself takes anywhere between 40-70ms the non minified CSS is a whopping 9085 lines. The parser itself completes the object generation in anywhere between 3-10ms. Stringify-ing the object takes anywhere between 0.3-4ms Tested on an M1 Mac Mini

import {parseCss, stringify} from '../components/cssParser.mjs';

console.time('download'); // Start download timer

const css = await fetch('https://cdnjs.cloudflare.com/ajax/libs/materialize/1.0.0/css/materialize.min.css');
const cssText = await css.text();

console.timeEnd('download'); // End and log download timer

console.time('parse'); // Start parse timer

let cssObj = parseCss(cssText);

console.timeEnd('parse'); // End and log parse timer

console.time('string'); // Start stringify timer

let cssString = stringify(cssObj);

console.timeEnd('string'); // End and log stringify timer

Output:

download: 56.105ms
parse: 3.622ms
string: 0.714ms