0
# PostCSS Reduce Transforms
1

2
PostCSS Reduce Transforms is a PostCSS plugin that optimizes CSS transform functions by reducing them to their simplest equivalent forms. It converts complex 3D transform functions to simpler 2D equivalents where possible, consolidates redundant parameters, and reduces matrix3d functions to matrix when appropriate.
3

4
## Package Information
5

6
- **Package Name**: postcss-reduce-transforms
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install postcss-reduce-transforms`
10

11
## Core Imports
12

13
```javascript
14
const reduceTransforms = require('postcss-reduce-transforms');
15
```
16

17
For ES modules:
18

19
```javascript
20
import reduceTransforms from 'postcss-reduce-transforms';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const postcss = require('postcss');
27
const reduceTransforms = require('postcss-reduce-transforms');
28

29
// As part of a PostCSS processing chain
30
postcss([reduceTransforms()])
31
  .process(css, { from: undefined })
32
  .then(result => {
33
    console.log(result.css);
34
  });
35

36
// With other PostCSS plugins (typical usage)
37
const postcss = require('postcss');
38
const autoprefixer = require('autoprefixer');
39
const reduceTransforms = require('postcss-reduce-transforms');
40

41
postcss([
42
  autoprefixer,
43
  reduceTransforms(), // Usually run after other transform plugins
44
])
45
  .process(css, { from: 'input.css', to: 'output.css' })
46
  .then(result => {
47
    // Optimized CSS with reduced transform functions
48
    console.log(result.css);
49
  });
50
```
51

52
**Example transformation:**
53

54
Input CSS:
55
```css
56
h1 {
57
  transform: rotate3d(0, 0, 1, 20deg);
58
}
59
```
60

61
Output CSS:
62
```css
63
h1 {
64
  transform: rotate(20deg);
65
}
66
```
67

68
## Architecture
69

70
PostCSS Reduce Transforms is built around several key components:
71

72
- **Plugin Creator Function**: The main export that returns a configured PostCSS plugin instance with the `postcssPlugin` name and `prepare()` method
73
- **Value Parser Integration**: Uses `postcss-value-parser` to parse and manipulate CSS transform function syntax trees
74
- **Reduction Engine**: A map-based system with specialized reducer functions for each transform type (matrix3d, rotate3d, scale, etc.)
75
- **AST Walker**: Traverses parsed transform values and applies appropriate reductions using the `walk()` method
76
- **Caching System**: Internal value cache to avoid re-processing identical transform declarations
77
- **CSS Variable Preservation**: Special handling to preserve `var()` and `env()` functions during optimization
78

79
The plugin processes CSS declarations matching `/transform$/i` (including vendor prefixes) in the `OnceExit` phase, ensuring all transforms are optimized after the CSS has been fully processed.
80

81
## Capabilities
82

83
### Plugin Creator
84

85
Creates a PostCSS plugin instance that processes CSS transform declarations and optimizes them.
86

87
```javascript { .api }
88
/**
89
 * Creates a PostCSS plugin that reduces CSS transform functions
90
 * @returns {import('postcss').Plugin} PostCSS plugin instance
91
 */
92
function reduceTransforms(): Plugin;
93
```
94

95
The plugin automatically processes all CSS declarations matching the pattern `/transform$/i` (including `transform`, `Transform`, `-webkit-transform`, etc.) and applies the following optimizations:
96

97
### Matrix3D Reduction
98

99
Converts `matrix3d` functions to simpler `matrix` equivalents when possible.
100

101
**Transformation Rule:**
102
- `matrix3d(a, b, 0, 0, c, d, 0, 0, 0, 0, 1, 0, tx, ty, 0, 1)` → `matrix(a, b, c, d, tx, ty)`
103

104
**Example:**
105
```css
106
/* Input */
107
transform: matrix3d(20, 20, 0, 0, 40, 40, 0, 0, 0, 0, 1, 0, 80, 80, 0, 1);
108

109
/* Output */
110
transform: matrix(20, 20, 40, 40, 80, 80);
111
```
112

113
### Rotate3D Reduction
114

115
Converts `rotate3d` functions to their axis-specific equivalents.
116

117
**Transformation Rules:**
118
- `rotate3d(1, 0, 0, a)` → `rotateX(a)`
119
- `rotate3d(0, 1, 0, a)` → `rotateY(a)`
120
- `rotate3d(0, 0, 1, a)` → `rotate(a)`
121

122
**Examples:**
123
```css
124
/* Input */
125
transform: rotate3d(1, 0, 0, 45deg);
126
transform: rotate3d(0, 1, 0, 90deg);
127
transform: rotate3d(0, 0, 1, 180deg);
128

129
/* Output */
130
transform: rotateX(45deg);
131
transform: rotateY(90deg);
132
transform: rotate(180deg);
133
```
134

135
### RotateZ Reduction
136

137
Converts `rotateZ` functions to simpler `rotate` equivalents.
138

139
**Transformation Rule:**
140
- `rotateZ(rz)` → `rotate(rz)`
141

142
**Example:**
143
```css
144
/* Input */
145
transform: rotateZ(45deg);
146

147
/* Output */
148
transform: rotate(45deg);
149
```
150

151
### Scale Reduction
152

153
Optimizes `scale` functions by removing redundant parameters.
154

155
**Transformation Rules:**
156
- `scale(sx, sy)` → `scale(sx)` when sx === sy
157
- `scale(sx, 1)` → `scaleX(sx)`
158
- `scale(1, sy)` → `scaleY(sy)`
159

160
**Examples:**
161
```css
162
/* Input */
163
transform: scale(2, 2);
164
transform: scale(1.5, 1);
165
transform: scale(1, 0.8);
166

167
/* Output */
168
transform: scale(2);
169
transform: scaleX(1.5);
170
transform: scaleY(0.8);
171
```
172

173
### Scale3D Reduction
174

175
Converts `scale3d` functions to their axis-specific equivalents when possible.
176

177
**Transformation Rules:**
178
- `scale3d(sx, 1, 1)` → `scaleX(sx)`
179
- `scale3d(1, sy, 1)` → `scaleY(sy)`
180
- `scale3d(1, 1, sz)` → `scaleZ(sz)`
181

182
**Examples:**
183
```css
184
/* Input */
185
transform: scale3d(2, 1, 1);
186
transform: scale3d(1, 1.5, 1);
187
transform: scale3d(1, 1, 0.5);
188

189
/* Output */
190
transform: scaleX(2);
191
transform: scaleY(1.5);
192
transform: scaleZ(0.5);
193
```
194

195
### Translate Reduction
196

197
Optimizes `translate` functions by removing zero values and converting to axis-specific functions.
198

199
**Transformation Rules:**
200
- `translate(tx, 0)` → `translate(tx)`
201
- `translate(0, ty)` → `translateY(ty)`
202

203
**Examples:**
204
```css
205
/* Input */
206
transform: translate(100px, 0);
207
transform: translate(0, 50px);
208

209
/* Output */
210
transform: translate(100px);
211
transform: translateY(50px);
212
```
213

214
### Translate3D Reduction
215

216
Converts `translate3d` functions to `translateZ` when X and Y are zero.
217

218
**Transformation Rule:**
219
- `translate3d(0, 0, tz)` → `translateZ(tz)`
220

221
**Example:**
222
```css
223
/* Input */
224
transform: translate3d(0, 0, 10px);
225

226
/* Output */
227
transform: translateZ(10px);
228
```
229

230
## Type Definitions
231

232
```typescript { .api }
233
declare function reduceTransforms(): import("postcss").Plugin;
234
declare namespace reduceTransforms {
235
    let postcss: true;
236
}
237
```
238

239
## CSS Variable Support
240

241
The plugin preserves CSS variables (`var()` and `env()` functions) without modification:
242

243
```css
244
/* Input */
245
transform: scale(var(--scale-x), var(--scale-y));
246

247
/* Output - preserved as-is */
248
transform: scale(var(--scale-x), var(--scale-y));
249
```
250

251
## Case Insensitive Processing
252

253
All transform function names are processed case-insensitively:
254

255
```css
256
/* Input */
257
transform: ROTATEZ(90deg);
258
transform: SCALE3D(2, 1, 1);
259

260
/* Output */
261
transform: rotate(90deg);
262
transform: scaleX(2);
263
```
264

265
## Performance Optimization
266

267
The plugin includes internal caching to avoid re-processing identical transform values, improving performance when the same transform declarations appear multiple times in a stylesheet.
268

269
## Dependencies
270

271
- **postcss-value-parser**: ^4.2.0 - Used for parsing and manipulating CSS transform values
272
- **postcss**: ^8.4.32 - Peer dependency for PostCSS plugin system