0
# postcss-merge-longhand
1

2
postcss-merge-longhand is a PostCSS plugin that optimizes CSS by merging longhand properties into their shorthand equivalents. It automatically combines related longhand properties (like margin-top, margin-right, margin-bottom, margin-left) into concise shorthand declarations (like margin: 10px 20px) when possible, reducing file size and improving performance.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const plugin = require("postcss-merge-longhand");
15
```
16

17
For ES modules:
18

19
```javascript
20
import plugin from "postcss-merge-longhand";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const postcss = require("postcss");
27
const mergeLonghand = require("postcss-merge-longhand");
28

29
// Create PostCSS processor with the plugin
30
const processor = postcss([mergeLonghand()]);
31

32
// Process CSS
33
const result = processor.process(`
34
  h1 {
35
    margin-top: 10px;
36
    margin-right: 20px;
37
    margin-bottom: 10px;
38
    margin-left: 20px;
39
  }
40
`);
41

42
// Output: h1 { margin: 10px 20px; }
43
console.log(result.css);
44
```
45

46
## Capabilities
47

48
### Plugin Creator Function
49

50
Creates a PostCSS plugin instance that merges longhand properties into shorthand equivalents.
51

52
```javascript { .api }
53
/**
54
 * Creates a PostCSS plugin instance for merging longhand properties
55
 * @returns {Plugin} PostCSS plugin object
56
 */
57
function pluginCreator(): Plugin;
58

59
/** Plugin creator has postcss property set to true */
60
pluginCreator.postcss: true;
61
```
62

63
### Plugin Object
64

65
The PostCSS plugin object returned by the plugin creator.
66

67
```javascript { .api }
68
interface Plugin {
69
  /** Plugin name identifier */
70
  postcssPlugin: "postcss-merge-longhand";
71
  /** Processing function that runs once after CSS parsing */
72
  OnceExit(css: PostCSSRoot): void;
73
}
74

75
interface PostCSSRoot {
76
  /** Walk through all rules in the CSS AST */
77
  walkRules(callback: (rule: PostCSSRule) => void): void;
78
}
79

80
interface PostCSSRule {
81
  /** Walk through all declarations in this rule */
82
  walkDecls(callback: (decl: PostCSSDeclaration) => void): void;
83
  /** Walk through declarations matching a property pattern */
84
  walkDecls(prop: RegExp | string, callback: (decl: PostCSSDeclaration) => void): void;
85
}
86

87
interface PostCSSDeclaration {
88
  /** CSS property name */
89
  prop: string;
90
  /** CSS property value */
91
  value: string;
92
  /** Whether the declaration is marked as !important */
93
  important: boolean;
94
  /** Parent rule or at-rule */
95
  parent: PostCSSRule | null;
96
  /** Remove this declaration from its parent */
97
  remove(): void;
98
}
99
```
100

101
### Supported Property Groups
102

103
The plugin processes these CSS property groups:
104

105
#### Margin Properties
106
- `margin` - Margin shorthand
107
- `margin-top`, `margin-right`, `margin-bottom`, `margin-left` - Directional margins
108

109
#### Padding Properties  
110
- `padding` - Padding shorthand
111
- `padding-top`, `padding-right`, `padding-bottom`, `padding-left` - Directional padding
112

113
#### Border Properties
114
- `border` - General border shorthand (width, style, color)
115
- `border-top`, `border-right`, `border-bottom`, `border-left` - Directional borders
116
- `border-width`, `border-style`, `border-color` - Border aspect shorthands
117
- `border-top-width`, `border-right-width`, `border-bottom-width`, `border-left-width` - Directional border widths
118
- `border-top-style`, `border-right-style`, `border-bottom-style`, `border-left-style` - Directional border styles  
119
- `border-top-color`, `border-right-color`, `border-bottom-color`, `border-left-color` - Directional border colors
120
- `border-spacing` - Table border spacing (also minified when appropriate)
121

122
#### Column Properties
123
- `columns` - Columns shorthand
124
- `column-width`, `column-count` - Column longhand properties
125

126
## Usage Examples
127

128
### Basic Margin Merging
129

130
Input CSS:
131
```css
132
.box {
133
  margin-top: 10px;
134
  margin-right: 15px;
135
  margin-bottom: 10px;  
136
  margin-left: 15px;
137
}
138
```
139

140
Output CSS:
141
```css
142
.box {
143
  margin: 10px 15px;
144
}
145
```
146

147
### Border Property Optimization
148

149
Input CSS:
150
```css
151
.card {
152
  border-top-width: 2px;
153
  border-right-width: 2px;
154
  border-bottom-width: 2px;
155
  border-left-width: 2px;
156
  border-top-style: solid;
157
  border-right-style: solid;
158
  border-bottom-style: solid;
159
  border-left-style: solid;
160
  border-top-color: red;
161
  border-right-color: red;
162
  border-bottom-color: red;
163
  border-left-color: red;
164
}
165
```
166

167
Output CSS:
168
```css
169
.card {
170
  border: 2px solid red;
171
}
172
```
173

174
### Column Property Merging
175

176
Input CSS:
177
```css
178
.layout {
179
  column-width: 200px;
180
  column-count: 3;
181
}
182
```
183

184
Output CSS:
185
```css
186
.layout {
187
  columns: 200px 3;
188
}
189
```
190

191
### Integration with PostCSS
192

193
```javascript
194
const postcss = require("postcss");
195
const mergeLonghand = require("postcss-merge-longhand");
196
const autoprefixer = require("autoprefixer");
197

198
// Use with other PostCSS plugins
199
const processor = postcss([
200
  autoprefixer(),
201
  mergeLonghand(),
202
  // Add other optimization plugins
203
]);
204

205
processor.process(cssString, { from: undefined })
206
  .then(result => {
207
    console.log(result.css);
208
  });
209
```
210

211
### Build Tool Integration
212

213
```javascript
214
// webpack.config.js
215
module.exports = {
216
  module: {
217
    rules: [
218
      {
219
        test: /\.css$/,
220
        use: [
221
          "style-loader",
222
          "css-loader",
223
          {
224
            loader: "postcss-loader",
225
            options: {
226
              postcssOptions: {
227
                plugins: [
228
                  require("postcss-merge-longhand")(),
229
                ]
230
              }
231
            }
232
          }
233
        ]
234
      }
235
    ]
236
  }
237
};
238
```
239

240
## Optimization Behavior
241

242
The plugin performs several types of optimizations:
243

244
1. **Directional Property Merging**: Combines directional properties (top, right, bottom, left) into shorthand when values allow for compression
245
2. **Duplicate Removal**: Removes duplicate and redundant property declarations
246
3. **Value Minimization**: Shortens property values using standard CSS shorthand rules
247
4. **Precedence Handling**: Respects CSS cascade and specificity rules
248
5. **Style Hack Detection**: Preserves CSS hacks and browser-specific workarounds
249

250
## Dependencies
251

252
This plugin requires PostCSS as a peer dependency:
253

254
```json
255
{
256
  "peerDependencies": {
257
    "postcss": "^8.4.32"
258
  }
259
}
260
```
261

262
Internal dependencies:
263
- `postcss-value-parser` - For parsing and manipulating CSS values
264
- `stylehacks` - For detecting and preserving CSS hacks
265

266
## Error Handling
267

268
The plugin gracefully handles various edge cases:
269

270
- **Invalid CSS values**: Malformed or unparseable values are preserved as-is
271
- **Mixed importance levels**: Properties with different `!important` declarations are not merged
272
- **Style hacks**: Browser-specific CSS hacks are detected and preserved
273
- **Custom properties**: CSS variables are preserved and not processed
274
- **Incomplete property sets**: Partial longhand property sets are only merged when safe
275

276
## Limitations
277

278
- Preserves CSS custom properties (CSS variables) and doesn't merge properties containing them
279
- Respects `!important` declarations and doesn't merge properties with different importance levels
280
- Maintains browser-specific style hacks and doesn't optimize them away
281
- Only merges properties within the same CSS rule - doesn't merge across different selectors
282
- Requires PostCSS version 8.4.32 or higher
283
- Does not process properties inside CSS-in-JS template literals or other non-standard CSS contexts