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

Tooling & Type-Checking

CSS Crunch keeps its developer toolchain fast and modern. The type-check step of the check script runs on TypeScript 7 via tsgo (the native Go port of the compiler), while bundling and dual CJS/ESM output are handled by tsdown (built on Rolldown, in Rust).

Measured on this repository (Apple Silicon):

| Step | Classic tooling | Native (TS 7 / tsgo) | Speedup | | --- | --- | --- | --- | | Type-check (--noEmit) | ~0.34 s (tsc 6.0.3) | ~0.10 s (tsgo) | ~3.4× |

tsgo reports the exact same type errors as tsc. The bundle is produced by Rolldown (no type-checking during build) and the published .d.ts declarations are generated by the stable TypeScript compiler, so type safety is enforced separately by the check script.

Note: TypeScript 7 is still in preview. We use tsgo for type-checking only (it emits nothing), which is safe today. Generating declarations with the native compiler (dts: { tsgo: true } in tsdown.config.mts) is still experimental and kept opt-in until TS 7 reaches a stable release.

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.