0
# PostCSS Normalize Whitespace
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: postcss-normalize-whitespace
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install postcss-normalize-whitespace`
10
- **Version**: 7.0.1
11
- **License**: MIT
12

13
## Core Imports
14

15
```javascript
16
const normalizeWhitespace = require("postcss-normalize-whitespace");
17
```
18

19
For ES modules (using default import due to CommonJS export):
20
```javascript
21
import normalizeWhitespace from "postcss-normalize-whitespace";
22
```
23

24
## Basic Usage
25

26
```javascript
27
const postcss = require("postcss");
28
const normalizeWhitespace = require("postcss-normalize-whitespace");
29

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

34
// Example transformation
35
const input = `
36
h1 {
37
    width: calc(10px - ( 100px / var(--test) )) 
38
}
39
`;
40

41
const output = `
42
h1{
43
    width: calc(10px - 100px / var(--test))
44
}
45
`;
46
```
47

48
## Architecture
49

50
The plugin follows the standard PostCSS plugin architecture:
51
- **Plugin Creator Function**: Returns a PostCSS plugin object
52
- **OnceExit Hook**: Processes the entire CSS AST after parsing
53
- **Value Parser Integration**: Uses postcss-value-parser for intelligent whitespace handling
54
- **Caching System**: Optimizes performance by caching processed values
55

56
## Capabilities
57

58
### Plugin Creator
59

60
Creates a PostCSS plugin instance for whitespace normalization.
61

62
```javascript { .api }
63
/**
64
 * Creates a PostCSS plugin for normalizing whitespace in CSS
65
 * @returns {import('postcss').Plugin} PostCSS plugin object
66
 */
67
function normalizeWhitespace(): import('postcss').Plugin;
68

69
// PostCSS plugin identifier (static property)
70
normalizeWhitespace.postcss = true;
71
```
72

73
### Whitespace Normalization Features
74

75
The plugin automatically performs the following optimizations:
76

77
#### Declaration Whitespace Optimization
78
- Removes unnecessary whitespace around CSS property values
79
- Normalizes spacing in function calls (calc, var, env, etc.)
80
- Preserves necessary spacing in CSS custom properties and variable functions
81
- Optimizes !important declaration formatting
82

83
#### Rule and At-Rule Formatting
84
- Removes excess whitespace before CSS rules and at-rules
85
- Normalizes spacing between selectors and rule blocks
86
- Removes unnecessary semicolons and trailing whitespace
87

88
#### Special CSS Construct Handling
89
- **calc() functions**: Reduces whitespace while preserving mathematical operators
90
- **CSS Variables (var(), env(), constant())**: Preserves internal spacing for proper fallback handling
91
- **Custom Properties**: Ensures empty custom properties maintain required space
92
- **IE9 Hacks**: Normalizes whitespace around legacy browser hacks
93

94
### Example Transformations
95

96
**Input CSS:**
97
```css
98
h1 {
99
    width: calc(10px - ( 100px / var(--test) )) ;
100
    --custom-prop:  ;
101
    color: red  !important ;
102
}
103
```
104

105
**Output CSS:**
106
```css
107
h1{
108
    width:calc(10px - 100px / var(--test));
109
    --custom-prop: ;
110
    color:red!important
111
}
112
```
113

114
## Configuration
115

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

118
## Browser and Environment Compatibility
119

120
- **Node.js**: ^18.12.0 || ^20.9.0 || >=22.0
121
- **PostCSS**: ^8.4.32 (peer dependency)
122
- **Dependencies**: postcss-value-parser ^4.2.0
123

124
## Error Handling
125

126
The plugin is designed to be safe and non-destructive:
127
- Preserves functional CSS while optimizing formatting
128
- Maintains CSS custom property fallback behavior
129
- Handles complex nested functions correctly
130
- Does not modify CSS semantics, only formatting