0
# PostCSS Normalize Repeat Style
1
2
PostCSS Normalize Repeat Style is a PostCSS plugin that optimizes CSS by converting two-value background-repeat and mask-repeat syntax into single-value shorthand equivalents. This plugin reduces CSS file size while maintaining identical visual behavior, making it ideal for CSS optimization pipelines and build tools.
3
4
## Package Information
5
6
- **Package Name**: postcss-normalize-repeat-style
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install postcss-normalize-repeat-style`
10
11
## Core Imports
12
13
```javascript
14
const normalizeRepeatStyle = require("postcss-normalize-repeat-style");
15
```
16
17
For ES modules:
18
19
```javascript
20
import normalizeRepeatStyle from "postcss-normalize-repeat-style";
21
```
22
23
## Basic Usage
24
25
```javascript
26
const postcss = require("postcss");
27
const normalizeRepeatStyle = require("postcss-normalize-repeat-style");
28
29
const css = `
30
.element {
31
background: url(image.jpg) repeat no-repeat;
32
mask-repeat: no-repeat repeat;
33
}
34
`;
35
36
const result = postcss([normalizeRepeatStyle()])
37
.process(css, { from: undefined });
38
39
console.log(result.css);
40
// Output:
41
// .element {
42
// background: url(image.jpg) repeat-x;
43
// mask-repeat: repeat-y;
44
// }
45
```
46
47
## Capabilities
48
49
### Plugin Creator Function
50
51
Creates a PostCSS plugin instance that normalizes repeat-style values in CSS declarations.
52
53
```javascript { .api }
54
/**
55
* Creates a PostCSS plugin that normalizes background-repeat and mask-repeat values
56
* @returns {import('postcss').Plugin} PostCSS plugin instance
57
*/
58
function normalizeRepeatStyle(): import('postcss').Plugin;
59
```
60
61
The plugin automatically processes the following CSS properties:
62
- `background` (when containing repeat values)
63
- `background-repeat`
64
- `mask-repeat` (including vendor-prefixed variants like `-webkit-mask-repeat`)
65
66
### Plugin Properties
67
68
The plugin creator function includes a PostCSS marker property:
69
70
```javascript { .api }
71
normalizeRepeatStyle.postcss = true;
72
```
73
74
## Transformation Rules
75
76
The plugin applies the following transformations to repeat values:
77
78
| Input Syntax | Output Syntax | Description |
79
|--------------|---------------|-------------|
80
| `repeat no-repeat` | `repeat-x` | Repeat horizontally only |
81
| `no-repeat repeat` | `repeat-y` | Repeat vertically only |
82
| `repeat repeat` | `repeat` | Repeat in both directions |
83
| `space space` | `space` | Space evenly in both directions |
84
| `round round` | `round` | Round spacing in both directions |
85
| `no-repeat no-repeat` | `no-repeat` | No repetition in either direction |
86
87
## Advanced Features
88
89
### CSS Variable Preservation
90
91
The plugin intelligently preserves CSS custom properties and variable functions to avoid breaking dynamic values:
92
93
```css
94
/* These remain unchanged */
95
.element {
96
background-repeat: var(--custom-repeat);
97
background: url(image.jpg) env(--repeat-value);
98
mask-repeat: constant(--mask-repeat);
99
}
100
```
101
102
Preserved variable functions:
103
- `var()` - CSS custom properties
104
- `env()` - Environment variables
105
- `constant()` - Legacy environment variables
106
107
### Multiple Background Support
108
109
The plugin correctly handles multiple background layers separated by commas:
110
111
```css
112
/* Input */
113
.element {
114
background:
115
url(bg1.jpg) repeat no-repeat,
116
url(bg2.jpg) no-repeat repeat;
117
}
118
119
/* Output */
120
.element {
121
background:
122
url(bg1.jpg) repeat-x,
123
url(bg2.jpg) repeat-y;
124
}
125
```
126
127
### Background Size Preservation
128
129
The plugin avoids processing values after the background-size separator (`/`) to prevent incorrect transformations:
130
131
```css
132
/* Input - size values after '/' are preserved */
133
.element {
134
background: url(image.jpg) repeat no-repeat / 100px 50px;
135
}
136
137
/* Output */
138
.element {
139
background: url(image.jpg) repeat-x / 100px 50px;
140
}
141
```
142
143
### Performance Optimization
144
145
The plugin includes built-in caching to avoid redundant processing of identical values, improving build performance for large stylesheets.
146
147
## Usage Examples
148
149
### PostCSS Configuration
150
151
```javascript
152
// postcss.config.js
153
module.exports = {
154
plugins: [
155
require('postcss-normalize-repeat-style'),
156
// other plugins...
157
]
158
};
159
```
160
161
### Gulp Integration
162
163
```javascript
164
const gulp = require('gulp');
165
const postcss = require('gulp-postcss');
166
const normalizeRepeatStyle = require('postcss-normalize-repeat-style');
167
168
gulp.task('css', () => {
169
return gulp.src('src/**/*.css')
170
.pipe(postcss([
171
normalizeRepeatStyle(),
172
]))
173
.pipe(gulp.dest('dist'));
174
});
175
```
176
177
### Webpack Integration
178
179
```javascript
180
// webpack.config.js
181
module.exports = {
182
module: {
183
rules: [
184
{
185
test: /\.css$/,
186
use: [
187
'style-loader',
188
'css-loader',
189
{
190
loader: 'postcss-loader',
191
options: {
192
postcssOptions: {
193
plugins: [
194
require('postcss-normalize-repeat-style'),
195
],
196
},
197
},
198
},
199
],
200
},
201
],
202
},
203
};
204
```
205
206
## Dependencies
207
208
### Runtime Dependencies
209
210
```javascript { .api }
211
// postcss-value-parser: ^4.2.0
212
// Used for parsing and manipulating CSS values
213
```
214
215
### Peer Dependencies
216
217
```javascript { .api }
218
// postcss: ^8.4.31
219
// The PostCSS processor framework
220
```
221
222
## Types
223
224
```typescript { .api }
225
// TypeScript definitions available at types/index.d.ts
226
interface PluginCreator {
227
(): import('postcss').Plugin;
228
postcss: true;
229
}
230
231
// Plugin returns standard PostCSS Plugin interface
232
// postcss.Plugin interface includes:
233
// - postcssPlugin: string (plugin name identifier)
234
// - prepare(): object with processor methods like OnceExit
235
```