PostCSS Normalize Unicode

PostCSS Normalize Unicode is a PostCSS plugin that normalizes unicode-range descriptors in CSS @font-face rules. It intelligently converts ranges like u+2b00-2bff into more compact wildcard representations like u+2b?? when the range covers complete hex digit positions, resulting in smaller CSS output while maintaining browser compatibility.

Package Information

• Package Name: postcss-normalize-unicode
• Package Type: npm
• Language: JavaScript
• Installation: npm install postcss-normalize-unicode

Core Imports

const postcssNormalizeUnicode = require("postcss-normalize-unicode");

For ES modules:

import postcssNormalizeUnicode from "postcss-normalize-unicode";

Basic Usage

const postcss = require("postcss");
const postcssNormalizeUnicode = require("postcss-normalize-unicode");

// Basic usage without options
const result = await postcss([
  postcssNormalizeUnicode()
]).process(css, { from: undefined });

// With browserslist override
const result = await postcss([
  postcssNormalizeUnicode({
    overrideBrowserslist: ['defaults', 'not ie <=11']
  })
]).process(css, { from: undefined });

Input CSS:

@font-face {
  font-family: test;
  unicode-range: u+2b00-2bff;
}

Output CSS:

@font-face {
  font-family: test;
  unicode-range: u+2b??;
}

Architecture

The plugin operates by:

1. Browser Detection: Uses browserslist to determine target browsers and detect legacy IE/Edge compatibility requirements
2. CSS Processing: Walks through all unicode-range declarations in CSS during the OnceExit phase
3. Value Parsing: Uses postcss-value-parser to safely parse and transform unicode-range values
4. Range Optimization: Converts unicode ranges to wildcard patterns using the internal algorithm:
   • Parses ranges like u+2b00-2bff into start/end bounds
   • Compares hex digit positions from left to right
   • Converts positions where start=0 and end=f to wildcard (?)
   • Supports up to 5 wildcard characters maximum
   • Falls back to original range if optimization isn't possible
5. Legacy Support: Automatically converts lowercase 'u' prefixes to uppercase 'U' for IE ≤11 and Edge ≤15
6. Performance Optimization: Implements caching to avoid re-processing identical values

Capabilities

Plugin Creator

Creates a PostCSS plugin instance for normalizing unicode-range descriptors.

/**
 * Creates a PostCSS plugin for normalizing unicode-range descriptors
 * @param {Options} opts - Plugin configuration options
 * @returns {import('postcss').Plugin} PostCSS plugin instance
 */
function postcssNormalizeUnicode(opts?: Options): import('postcss').Plugin;

Unicode Range Normalization

The plugin automatically processes all unicode-range declarations and:

• Converts ranges like u+2b00-2bff to u+2b?? when possible
• Converts ranges like u+1e00-1eff to u+1e?? when possible
• Supports up to 5 wildcard characters (?) in range patterns
• Preserves ranges that cannot be optimized (e.g., u+2125-2128)
• Handles case normalization (converts to lowercase by default)
• Applies uppercase 'U' prefix for legacy browser compatibility when needed

Browser Compatibility Handling

Automatically detects and handles browser-specific requirements:

• Legacy browsers (IE ≤11, Edge ≤15): Converts to uppercase 'U' prefix
• Modern browsers: Uses lowercase 'u' prefix for smaller output
• Uses browserslist configuration for automatic browser detection

Configuration Options

interface Options {
  /** Override browserslist configuration for browser targeting */
  overrideBrowserslist?: string | string[];
  /** Custom usage statistics for browserslist */
  stats?: object;
  /** Custom path for browserslist config resolution */
  path?: string;
  /** Environment name for browserslist config */
  env?: string;
}

Configuration Properties

overrideBrowserslist

• Type: string | string[]
• Optional: Yes
• Description: Override the default browserslist configuration to target specific browsers
• Example: ['defaults', 'not ie <=11'] or 'IE 9'

stats

• Type: object
• Optional: Yes
• Description: Custom usage statistics for browserslist browser selection

path

• Type: string
• Optional: Yes
• Description: Custom path for browserslist configuration file resolution

env

• Type: string
• Optional: Yes
• Description: Environment name to use from browserslist configuration (e.g., 'production', 'legacy')

Usage Examples

Basic Plugin Usage

const postcss = require("postcss");
const postcssNormalizeUnicode = require("postcss-normalize-unicode");

const processor = postcss([postcssNormalizeUnicode()]);

const css = `
@font-face {
  font-family: 'MyFont';
  unicode-range: u+2b00-2bff, u+1e00-1eff;
}
`;

const result = await processor.process(css, { from: undefined });
console.log(result.css);
// Output: unicode-range: u+2b??, u+1e??;

Legacy Browser Support

// Force legacy browser compatibility
const processor = postcss([
  postcssNormalizeUnicode({
    overrideBrowserslist: 'IE 9'
  })
]);

const result = await processor.process(css, { from: undefined });
// Output will use uppercase 'U+2b??' instead of 'u+2b??'

Using Browserslist Environment

// Use specific browserslist environment
const processor = postcss([
  postcssNormalizeUnicode({
    env: 'legacy'
  })
]);

Multiple Range Processing

const postcss = require("postcss");
const postcssNormalizeUnicode = require("postcss-normalize-unicode");

const css = `
@font-face {
  font-family: 'Icons';
  unicode-range: u+2000-2fff, u+2120-212f, u+0-7f;
}
`;

const result = await postcss([postcssNormalizeUnicode()])
  .process(css, { from: undefined });

console.log(result.css);
// Output:
// @font-face {
//   font-family: 'Icons';
//   unicode-range: u+2???, u+212?, u+0-7f;
// }
//
// Transformations applied:
// u+2000-2fff → u+2??? (4-digit range to 3 wildcards)
// u+2120-212f → u+212? (4-digit range to 1 wildcard)
// u+0-7f → remains unchanged (cannot be optimized)

Browser Compatibility

• Modern browsers: Uses lowercase 'u' prefix (smaller output)
• IE ≤11: Requires uppercase 'U' prefix (automatically detected and applied)
• Edge ≤15: Requires uppercase 'U' prefix (automatically detected and applied)
• Edge 16+: Supports lowercase 'u' prefix

The plugin automatically detects browser requirements using browserslist configuration and applies the appropriate prefix casing.

Plugin Properties

The plugin exposes a PostCSS compatibility marker to indicate it's a valid PostCSS plugin:

// PostCSS plugin compatibility marker
postcssNormalizeUnicode.postcss = true;

Error Handling

The plugin handles various edge cases gracefully:

• Invalid ranges: Preserves original values for ranges that don't follow expected patterns
• Single values: Passes through unicode ranges that aren't ranges (no dash)
• Mismatched lengths: Preserves ranges where start and end have different hex digit lengths
• CSS variables and functions: Passes through var(), env(), and other CSS functions unchanged
• Unknown properties: Only processes unicode-range declarations, ignores other properties

Performance Features

• Caching: Results are cached during processing to avoid redundant transformations
• Lazy evaluation: Processing only occurs during PostCSS OnceExit phase for efficiency
• Minimal parsing: Uses postcss-value-parser for safe and efficient CSS value manipulation