Documentation

Installation

Install Classpresso as a dev dependency:

npm install classpresso --save-dev

Or with yarn/pnpm:

yarn add -D classpresso
pnpm add -D classpresso

Quick Start

1. Build your project

First, create a production build of your project:

npm run build

2. Analyze patterns

See what class patterns can be consolidated:

npx classpresso analyze --dir .next

3. Optimize

Apply optimizations to your build output:

npx classpresso optimize --dir .next

How It Works

Classpresso reduces browser work by consolidating repeated class patterns:

1. Scans your build output for class attributes
2. Identifies patterns that repeat (e.g., button styles appearing 50 times)
3. Generates short hash-based class names (e.g., cp-abc12)
4. Replaces verbose patterns with single consolidated classes
5. Creates CSS that maps the hash to original utilities

The result: Fewer classes = less browser work = faster style recalculation on every page load, DOM change, and user interaction.

Analyze Command

Analyze your build output without making changes:

classpresso analyze [options]

Options:
  -d, --dir <path>         Build directory (default: ".next")
  --min-occurrences <n>    Minimum pattern occurrences (default: 2)
  --min-classes <n>        Minimum classes per pattern (default: 2)
  --json                   Output results as JSON
  -v, --verbose            Show detailed pattern breakdown

Example:

$ npx classpresso analyze --dir dist --verbose

Found 67 consolidation opportunities

Pattern: "flex items-center justify-center gap-2"
  Occurrences: 45
  Classes removed: 180 (4 × 45)
  Browser work saved: ~50%

Pattern: "rounded-lg border bg-card shadow-sm"
  Occurrences: 32
  Classes removed: 128 (4 × 32)

Total class lookups eliminated: 12,510

Optimize Command

Apply optimizations to your build:

classpresso optimize [options]

Options:
  -d, --dir <path>         Build directory (default: ".next")
  --min-occurrences <n>    Minimum pattern occurrences (default: 2)
  --min-classes <n>        Minimum classes per pattern (default: 2)
  --dry-run                Show changes without writing files
  --backup                 Create .bak files before modifying
  --no-manifest            Don't generate manifest file
  -v, --verbose            Show detailed output

Report Command

Generate a report from an existing optimization:

classpresso report [options]

Options:
  -d, --dir <path>         Build directory (default: ".next")
  --format <type>          Output format: text, json, html (default: "text")

Configuration File

Create a classpresso.config.js file:

module.exports = {
  // Build directory to scan
  buildDir: '.next',

  // Consolidation thresholds
  minOccurrences: 2,    // Pattern must appear at least 2 times
  minClasses: 2,        // Pattern must have at least 2 classes
  minBytesSaved: 10,    // Must save at least 10 bytes

  // Hash configuration
  hashPrefix: 'cp-',    // Prefix for consolidated classes
  hashLength: 5,        // Hash length (5 = 1M+ combinations)

  // Output options
  manifest: true,       // Generate manifest.json
  backup: false,        // Create .bak files
}

Exclusion Rules

Prevent certain classes from being consolidated:

module.exports = {
  exclude: {
    // Prefix patterns (for JavaScript hooks)
    prefixes: ['js-', 'data-', 'hook-', 'track-'],

    // Suffix patterns
    suffixes: ['-handler', '-trigger'],

    // Exact class names
    classes: ['no-consolidate'],

    // Regex patterns (for testing selectors)
    patterns: [/^qa-/, /^test-/, /^e2e-/],
  }
}

Thresholds

Control what patterns get consolidated:

Next.js Integration

Add Classpresso to your build process:

// package.json
{
  "scripts": {
    "build": "next build && classpresso optimize",
    "build:analyze": "next build && classpresso analyze"
  }
}

Vite Integration

Run after Vite build:

// package.json
{
  "scripts": {
    "build": "vite build && classpresso optimize --dir dist"
  }
}

Astro Integration

Run after Astro build:

// package.json
{
  "scripts": {
    "build": "astro build && classpresso optimize --dir dist"
  }
}