CSS Crunch

This package provides a powerful and efficient TypeScript library for optimizing CSS strings. It enables developers to easily compress css JavaScript projects.

The great focus is on keeping a great compatibility across all kind of render engine especially on the various Outlook.

Go here to the online and interactive playground

Compatibility

• Node.js: Officially supports Node 22, 24, and 26.
• Module Resolution: Full support for NodeNext and ESM/CommonJS environments.

Features

• Group rules: Group same rules with one selector.
• Compress: Compress the size by removing not necessary char.
• Merge selector: Merge same selector into only one.
• Media Query: Move all media queries at the bottom.

Installation

npm install @gafreax/csscrunch

Usage

// ESM
import csscrunch from '@gafreax/csscrunch'
const { default: compile } = csscrunch

const cssString = '.example { color: red; font-size: 16px; }';
const parsedCSS = compile(cssString);

// CommonJS
const csscrunch = require('@gafreax/csscrunch')
const { default: compile } = csscrunch

const cssString = '.example { color: red; font-size: 16px; }';
const parsedCSS = compile(cssString);

Optimization

To enable the optimization pass a Optimizations object (file: src/lib/optimization.d.ts) to the instance:

interface Optimizations {
  paddingShortHand?: boolean
  marginShortHand?: boolean
  removeZeroUnits?: boolean
}

CLI Usage

Quickly clean up your Css:

To optimize your CSS file, simply run the following command in your terminal:

$ npm start -- compile input.css optimized.css

Or via npx

$ npx @gafreax/csscrunch compile input.css optimized.css

Or via global install

$ npm install -g @gafreaxa/csscrunch
$ csscrunch compile input.css optimized.css

You can also use the flags: --optimize-short-hand to optimize padding and margin short hand --optimize-margin to optimize margin short hand --optimize-padding to optimize padding short hand --remove-zero-units to remove zero units --optimize-all to enable all optimizations Example:

$ npx @gafreax/csscrunch compile --optimize-all input.css optimized.css

Benchmark & Performance

CSS Crunch is built for speed and efficiency. It significantly outperforms traditional tools in both execution time and optimization size.

🚀 CSS Crunch vs. clean-css

We provide a dedicated benchmark comparison against clean-css, demonstrating CSS Crunch's superior throughput and compression capabilities.

To run the performance comparison script:

tsx benchmark/comparison.ts

For detailed visual reports on throughput and size, check out our documentation site.

Vitest Benchmarks

To run the standard suite of internal benchmarks:

pnpm run test:bench

Contribution

We welcome contributions to this open-source project. If you encounter issues or have suggestions for improvement, please feel free to create GitHub issues or submit pull requests.