or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

advanced-features.md batch-processing.md compatibility.md constructor-options.md index.md input-output.md optimization-levels.md

tile.json

Compatibility and Browser Support

Clean-CSS provides extensive browser compatibility configuration to ensure minified CSS works correctly across different browser versions and environments.

Compatibility Configuration

interface CompatibilityOptions {
  compatibility: string | CompatibilityObject;
}

type CompatibilityMode = '*' | 'ie11' | 'ie10' | 'ie9' | 'ie8' | 'ie7';

interface CompatibilityObject {
  colors?: ColorCompatibility;
  customUnits?: CustomUnitsCompatibility;
  properties?: PropertyCompatibility;
  selectors?: SelectorCompatibility;
  units?: UnitCompatibility;
}

Predefined Compatibility Modes

Clean-CSS includes several predefined compatibility mode shortcuts:

Universal Mode (Default)

const minifier = new CleanCSS({ compatibility: '*' });
// Equivalent to ie10+ compatibility

Internet Explorer Modes

const ie11Minifier = new CleanCSS({ compatibility: 'ie11' });
const ie10Minifier = new CleanCSS({ compatibility: 'ie10' });
const ie9Minifier = new CleanCSS({ compatibility: 'ie9' });
const ie8Minifier = new CleanCSS({ compatibility: 'ie8' });
const ie7Minifier = new CleanCSS({ compatibility: 'ie7' });

Each mode progressively disables features not supported by that browser version.

Color Compatibility

interface ColorCompatibility {
  hexAlpha?: boolean;     // 4- and 8-character hex color support (#RGBA, #RRGGBBAA)
  opacity?: boolean;      // rgba() and hsla() color support
}

Color Configuration

const colorCompatibleMinifier = new CleanCSS({
  compatibility: {
    colors: {
      hexAlpha: false,    // Disable #RGBA and #RRGGBBAA formats
      opacity: true       // Keep rgba() and hsla() functions
    }
  }
});

// Example transformations:
// With hexAlpha: false
// #fff8 → rgba(255,255,255,.533)
// With opacity: false
// rgba(255,0,0,0.5) → fallback or alternative format

Custom Units Compatibility

interface CustomUnitsCompatibility {
  rpx?: boolean;     // Support for rpx units (responsive pixels)
}

Custom Units Configuration

const customUnitsMinifier = new CleanCSS({
  compatibility: {
    customUnits: {
      rpx: true   // Enable rpx unit support (commonly used in mobile development)
    }
  }
});

// With rpx: true
// width: 750rpx; → kept as-is
// With rpx: false  
// width: 750rpx; → optimized or converted based on context

Property Compatibility

interface PropertyCompatibility {
  backgroundClipMerging?: boolean;      // Merge background-clip into shorthand
  backgroundOriginMerging?: boolean;    // Merge background-origin into shorthand  
  backgroundSizeMerging?: boolean;      // Merge background-size into shorthand
  colors?: boolean;                     // Enable color optimizations
  ieBangHack?: boolean;                 // Keep IE !important hack
  ieFilters?: boolean;                  // Keep IE filter and -ms-filter
  iePrefixHack?: boolean;               // Keep IE underscore prefix hack
  ieSuffixHack?: boolean;               // Keep IE suffix hack (\9)
  merging?: boolean;                    // Property merging based on browser understanding
  shorterLengthUnits?: boolean;         // Convert px to pc/pt/in when shorter
  spaceAfterClosingBrace?: boolean;     // Keep space after closing brace in url()
  urlQuotes?: boolean;                  // Keep quotes inside url() functions
  zeroUnits?: boolean;                  // Remove units from zero values
}

Property Compatibility Examples

const ieCompatibleMinifier = new CleanCSS({
  compatibility: {
    properties: {
      ieBangHack: true,        // Keep: color: red !ie;
      ieFilters: true,         // Keep: filter: alpha(opacity=50);
      iePrefixHack: true,      // Keep: _width: 100px;
      ieSuffixHack: true,      // Keep: width: 100px\9;
      urlQuotes: false,        // url("image.jpg") → url(image.jpg)
      zeroUnits: false,        // Keep: margin: 0px;
      shorterLengthUnits: true // 12px → 1pc (when shorter)
    }
  }
});

Background Property Merging

const backgroundMergingMinifier = new CleanCSS({
  compatibility: {
    properties: {
      backgroundClipMerging: true,    // Merge background-clip
      backgroundOriginMerging: true,  // Merge background-origin
      backgroundSizeMerging: false    // Don't merge background-size (IE compatibility)
    }
  }
});

// With backgroundSizeMerging: true (modern browsers)
// background-image: url(bg.jpg);
// background-size: cover;
// → background: url(bg.jpg) cover;

// With backgroundSizeMerging: false (IE compatibility)
// Keeps properties separate for older browsers

Selector Compatibility

interface SelectorCompatibility {
  adjacentSpace?: boolean;              // Space in adjacent sibling selectors
  attribute?: boolean;                  // Attribute selector optimizations
  ie7Hack?: boolean;                   // Keep IE7 * html hack
  multiplePseudoMerging?: boolean;     // Merge multiple pseudo selectors
  mergeLimit?: number;                 // Maximum selectors per rule
}

Selector Configuration

const selectorCompatibleMinifier = new CleanCSS({
  compatibility: {
    selectors: {
      adjacentSpace: true,           // Keep space in: h1 + p
      ie7Hack: true,                // Keep: * html .class
      multiplePseudoMerging: false, // Don't merge: :hover:focus
      mergeLimit: 8191              // IE selector limit
    }
  }
});

Selector Merge Limit

Internet Explorer has a limit on the number of selectors in a single rule. Configure this limit:

const ieSelectorLimitMinifier = new CleanCSS({
  compatibility: {
    selectors: {
      mergeLimit: 4095  // IE9+ limit
    }
  }
});

// Prevents creating rules with too many selectors:
// .a, .b, .c, ... (up to mergeLimit)

Unit Compatibility

interface UnitCompatibility {
  ch?: boolean;          // ch unit support
  in?: boolean;          // in unit support  
  pc?: boolean;          // pc unit support
  pt?: boolean;          // pt unit support
  rem?: boolean;         // rem unit support
  vh?: boolean;          // vh unit support
  vm?: boolean;          // vm unit support (old vmin)
  vmax?: boolean;        // vmax unit support
  vmin?: boolean;        // vmin unit support
  vw?: boolean;          // vw unit support
}

Unit Configuration

const unitCompatibleMinifier = new CleanCSS({
  compatibility: {
    units: {
      rem: false,     // Don't use rem units (IE8 compatibility)
      vh: false,      // Don't use vh units
      vw: false,      // Don't use vw units  
      vmin: false,    // Don't use vmin units
      ch: false       // Don't use ch units
    }
  }
});

// With rem: false
// 1.5rem → 24px (if base font size is 16px)

Complete Compatibility Examples

Modern Browser Configuration

const modernMinifier = new CleanCSS({
  compatibility: {
    colors: {
      hexAlpha: true,
      opacity: true
    },
    properties: {
      backgroundClipMerging: true,
      backgroundOriginMerging: true,
      backgroundSizeMerging: true,
      shorterLengthUnits: true,
      urlQuotes: false,
      zeroUnits: true
    },
    selectors: {
      multiplePseudoMerging: true,
      mergeLimit: -1  // No limit
    },
    units: {
      rem: true,
      vh: true,
      vw: true,
      vmin: true,
      vmax: true,
      ch: true
    }
  }
});

Internet Explorer 8 Configuration

const ie8Minifier = new CleanCSS({
  compatibility: {
    colors: {
      hexAlpha: false,
      opacity: false
    },
    properties: {
      backgroundClipMerging: false,
      backgroundOriginMerging: false,
      backgroundSizeMerging: false,
      ieBangHack: true,
      ieFilters: true,
      iePrefixHack: true,
      ieSuffixHack: true,
      shorterLengthUnits: false,
      urlQuotes: true
    },
    selectors: {
      ie7Hack: true,
      multiplePseudoMerging: false,
      mergeLimit: 4095
    },
    units: {
      rem: false,
      vh: false,
      vw: false,
      vmin: false,
      ch: false
    }
  }
});

Progressive Enhancement Setup

const progressiveMinifier = new CleanCSS({
  compatibility: {
    colors: {
      hexAlpha: true,     // Use modern color formats
      opacity: true
    },
    properties: {
      backgroundSizeMerging: false,  // Keep separate for fallbacks
      urlQuotes: true,               // Keep quotes for safety
      zeroUnits: true
    },
    selectors: {
      multiplePseudoMerging: false,  // Conservative merging
      mergeLimit: 4095               // IE-safe limit
    },
    units: {
      rem: true,      // Use rem with px fallbacks
      vh: true,       // Use viewport units
      vw: true
    }
  }
});

Compatibility Mode Effects

Color Handling

// Modern (hexAlpha: true, opacity: true):
// rgba(255,255,255,0.5) → #fff8
// hsla(0,100%,50%,0.8) → #ff0000cc

// Legacy (hexAlpha: false, opacity: false):  
// rgba(255,255,255,0.5) → kept as-is or converted to filter
// hsla(0,100%,50%,0.8) → rgb(255,0,0) with separate opacity

Property Merging

// Modern (all merging enabled):
// background-image: url(bg.jpg);
// background-size: cover;
// background-position: center;
// → background: url(bg.jpg) center/cover;

// IE Compatible (backgroundSizeMerging: false):
// background: url(bg.jpg) center;
// background-size: cover;

Unit Optimization

// Modern (shorterLengthUnits: true, all units enabled):
// margin: 16px 12px; → margin: 1pc; (when shorter)
// font-size: 14px; → font-size: 0.875rem;

// Legacy (shorterLengthUnits: false, limited units):
// Values kept in px units for maximum compatibility