PostCSS Normalize Whitespace

PostCSS Normalize Whitespace is a PostCSS plugin that normalizes and optimizes whitespace in CSS code by trimming unnecessary spaces inside and around CSS rules and declarations. It intelligently handles various CSS constructs including calc() functions, CSS custom properties (variables), and preserves necessary spacing while removing redundant whitespace.

Package Information

• Package Name: postcss-normalize-whitespace
• Package Type: npm
• Language: JavaScript
• Installation: npm install postcss-normalize-whitespace
• Version: 7.0.1
• License: MIT

Core Imports

const normalizeWhitespace = require("postcss-normalize-whitespace");

For ES modules (using default import due to CommonJS export):

import normalizeWhitespace from "postcss-normalize-whitespace";

Basic Usage

const postcss = require("postcss");
const normalizeWhitespace = require("postcss-normalize-whitespace");

// Use with PostCSS
const result = await postcss([normalizeWhitespace()])
  .process(css, { from: "input.css", to: "output.css" });

// Example transformation
const input = `
h1 {
    width: calc(10px - ( 100px / var(--test) )) 
}
`;

const output = `
h1{
    width: calc(10px - 100px / var(--test))
}
`;

Architecture

The plugin follows the standard PostCSS plugin architecture:

• Plugin Creator Function: Returns a PostCSS plugin object
• OnceExit Hook: Processes the entire CSS AST after parsing
• Value Parser Integration: Uses postcss-value-parser for intelligent whitespace handling
• Caching System: Optimizes performance by caching processed values

Capabilities

Plugin Creator

Creates a PostCSS plugin instance for whitespace normalization.

/**
 * Creates a PostCSS plugin for normalizing whitespace in CSS
 * @returns {import('postcss').Plugin} PostCSS plugin object
 */
function normalizeWhitespace(): import('postcss').Plugin;

// PostCSS plugin identifier (static property)
normalizeWhitespace.postcss = true;

Whitespace Normalization Features

The plugin automatically performs the following optimizations:

Declaration Whitespace Optimization

• Removes unnecessary whitespace around CSS property values
• Normalizes spacing in function calls (calc, var, env, etc.)
• Preserves necessary spacing in CSS custom properties and variable functions
• Optimizes !important declaration formatting

Rule and At-Rule Formatting

• Removes excess whitespace before CSS rules and at-rules
• Normalizes spacing between selectors and rule blocks
• Removes unnecessary semicolons and trailing whitespace

Special CSS Construct Handling

• calc() functions: Reduces whitespace while preserving mathematical operators
• CSS Variables (var(), env(), constant()): Preserves internal spacing for proper fallback handling
• Custom Properties: Ensures empty custom properties maintain required space
• IE9 Hacks: Normalizes whitespace around legacy browser hacks

Example Transformations

Input CSS:

h1 {
    width: calc(10px - ( 100px / var(--test) )) ;
    --custom-prop:  ;
    color: red  !important ;
}

Output CSS:

h1{
    width:calc(10px - 100px / var(--test));
    --custom-prop: ;
    color:red!important
}

Configuration

This plugin accepts no configuration options - it applies whitespace normalization automatically according to CSS optimization best practices.

Browser and Environment Compatibility

• Node.js: ^18.12.0 || ^20.9.0 || >=22.0
• PostCSS: ^8.4.32 (peer dependency)
• Dependencies: postcss-value-parser ^4.2.0

Error Handling

The plugin is designed to be safe and non-destructive:

• Preserves functional CSS while optimizing formatting
• Maintains CSS custom property fallback behavior
• Handles complex nested functions correctly
• Does not modify CSS semantics, only formatting