0
# PostCSS Minify Font Values
1
2
PostCSS Minify Font Values is a PostCSS plugin that optimizes CSS font declarations by minimizing font-family, font-weight, and font shorthand properties. It intelligently unquotes font families where safe, removes duplicates, converts font-weight keywords to numeric values, and can truncate font-family lists after generic keywords.
3
4
## Package Information
5
6
- **Package Name**: postcss-minify-font-values
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install postcss-minify-font-values`
10
- **Peer Dependencies**: postcss@^8.4.31
11
12
## Core Imports
13
14
```javascript
15
const minifyFontValues = require('postcss-minify-font-values');
16
```
17
18
ES Module:
19
20
```javascript
21
import minifyFontValues from 'postcss-minify-font-values';
22
```
23
24
## Basic Usage
25
26
```javascript
27
const postcss = require('postcss');
28
const minifyFontValues = require('postcss-minify-font-values');
29
30
// Basic usage
31
const css = `
32
h1 {
33
font: bold 2.2rem/.9 "Open Sans Condensed", sans-serif;
34
}
35
36
p {
37
font-family: "Helvetica Neue", Arial, sans-serif, Helvetica;
38
font-weight: normal;
39
}
40
`;
41
42
const result = await postcss([minifyFontValues()])
43
.process(css, { from: undefined });
44
45
console.log(result.css);
46
// Output:
47
// h1 {
48
// font: 700 2.2rem/.9 Open Sans Condensed,sans-serif
49
// }
50
//
51
// p {
52
// font-family: Helvetica Neue,Arial,sans-serif;
53
// font-weight: 400;
54
// }
55
```
56
57
## Architecture
58
59
PostCSS Minify Font Values follows the standard PostCSS plugin architecture with several key components:
60
61
- **Plugin Creator**: Factory function that accepts configuration and returns a PostCSS plugin instance
62
- **Transformation Pipeline**: Processes font-related declarations through specialized minification modules
63
- **Internal Caching**: Uses a Map-based cache to avoid reprocessing identical property-value combinations
64
- **Safety Mechanisms**: Detects CSS variable functions (`var()`, `env()`) and skips processing to preserve dynamic values
65
- **Modular Processing**: Separates concerns with dedicated modules for font-family, font-weight, and font shorthand optimization
66
67
The plugin operates during PostCSS's `OnceExit` phase, walking through all font-related declarations and applying optimizations while preserving the original CSS structure and functionality.
68
69
## Capabilities
70
71
### Plugin Creator Function
72
73
Creates a PostCSS plugin instance with configurable options.
74
75
```javascript { .api }
76
/**
77
* Creates a PostCSS plugin for minifying font values
78
* @param {Options} opts - Configuration options
79
* @returns {Plugin} PostCSS plugin instance
80
*/
81
function pluginCreator(opts?: Options): Plugin;
82
83
interface Options {
84
/** Remove font families after encountering generic keywords (default: false) */
85
removeAfterKeyword?: boolean;
86
/** Remove duplicate font families (default: true) */
87
removeDuplicates?: boolean;
88
/** Remove quotes from font families or custom function for CSS variables (default: true) */
89
removeQuotes?: boolean | ((prop: string) => '' | 'font' | 'font-family' | 'font-weight');
90
}
91
92
interface Plugin {
93
postcssPlugin: 'postcss-minify-font-values';
94
prepare(): ProcessorFunctions;
95
}
96
97
interface ProcessorFunctions {
98
OnceExit(css: Root): void;
99
}
100
```
101
102
**Usage Examples:**
103
104
```javascript
105
// Default options
106
const plugin = minifyFontValues();
107
108
// Custom options
109
const plugin = minifyFontValues({
110
removeAfterKeyword: true,
111
removeDuplicates: false,
112
removeQuotes: false
113
});
114
115
// CSS variable support with custom function
116
const plugin = minifyFontValues({
117
removeQuotes: (prop) => {
118
if (prop === '--font-family') return 'font-family';
119
if (prop === '--font-weight') return 'font-weight';
120
return '';
121
}
122
});
123
```
124
125
### Font Family Optimization
126
127
The plugin processes `font-family` declarations to optimize font family lists.
128
129
**Transformations applied:**
130
- **Quote removal**: Removes unnecessary quotes from font family names when safe
131
- **Duplicate removal**: Eliminates duplicate font family entries
132
- **Keyword truncation**: Optionally stops after generic keywords like `sans-serif`
133
134
```css
135
/* Input */
136
h1 { font-family: "Helvetica Neue", "Arial", "Helvetica Neue", sans-serif, "Times"; }
137
138
/* Output (default options) */
139
h1 { font-family: Helvetica Neue,Arial,sans-serif,Times; }
140
141
/* Output (removeAfterKeyword: true) */
142
h1 { font-family: Helvetica Neue,Arial,sans-serif; }
143
```
144
145
### Font Weight Optimization
146
147
The plugin converts `font-weight` keyword values to their numeric equivalents.
148
149
**Conversions:**
150
- `normal` → `400`
151
- `bold` → `700`
152
- Other values (100-900, bolder, lighter) remain unchanged
153
154
```css
155
/* Input */
156
p { font-weight: normal; }
157
h1 { font-weight: bold; }
158
159
/* Output */
160
p { font-weight: 400; }
161
h1 { font-weight: 700; }
162
```
163
164
### Font Shorthand Optimization
165
166
The plugin optimizes the CSS `font` shorthand property by applying font-family and font-weight optimizations while preserving other font properties.
167
168
```css
169
/* Input */
170
h1 { font: bold 16px/1.2 "Helvetica Neue", Arial, sans-serif; }
171
172
/* Output */
173
h1 { font: 700 16px/1.2 Helvetica Neue,Arial,sans-serif; }
174
```
175
176
### CSS Variable Support
177
178
When using CSS variables for font properties, pass a custom function to the `removeQuotes` option to identify which variables should be treated as font properties.
179
180
```javascript
181
const plugin = minifyFontValues({
182
removeQuotes: (prop) => {
183
// Map CSS variable names to font property types
184
if (prop === '--primary-font') return 'font-family';
185
if (prop === '--heading-weight') return 'font-weight';
186
if (prop === '--body-font') return 'font';
187
return ''; // Don't process other variables
188
}
189
});
190
```
191
192
```css
193
/* Input */
194
:root {
195
--primary-font: "Helvetica Neue", Arial, sans-serif;
196
--heading-weight: bold;
197
--other-var: "keep quotes";
198
}
199
200
/* Output */
201
:root {
202
--primary-font: Helvetica Neue,Arial,sans-serif;
203
--heading-weight: 700;
204
--other-var: "keep quotes";
205
}
206
```
207
208
## Configuration Options
209
210
### removeAfterKeyword
211
212
```javascript { .api }
213
removeAfterKeyword?: boolean
214
```
215
216
When `true`, removes font families from the list after encountering a generic font family keyword (`sans-serif`, `serif`, `fantasy`, `cursive`, `monospace`, `system-ui`).
217
218
Default: `false`
219
220
**Example:**
221
222
```javascript
223
// removeAfterKeyword: true
224
minifyFontValues({ removeAfterKeyword: true })
225
226
// Input: font-family: Arial, sans-serif, Times, serif;
227
// Output: font-family: Arial,sans-serif;
228
```
229
230
### removeDuplicates
231
232
```javascript { .api }
233
removeDuplicates?: boolean
234
```
235
236
When `true`, removes duplicate font family names from the font family list. Note that `monospace` is treated specially and duplicates are preserved.
237
238
Default: `true`
239
240
**Example:**
241
242
```javascript
243
// removeDuplicates: false
244
minifyFontValues({ removeDuplicates: false })
245
246
// Input: font-family: Arial, Helvetica, Arial, sans-serif;
247
// Output: font-family: Arial,Helvetica,Arial,sans-serif;
248
```
249
250
### removeQuotes
251
252
```javascript { .api }
253
removeQuotes?: boolean | ((prop: string) => '' | 'font' | 'font-family' | 'font-weight')
254
```
255
256
Controls quote removal from font family names. Can be a boolean or a function for CSS variable support.
257
258
- When `true` (default): Removes quotes when safe to do so
259
- When `false`: Preserves all quotes
260
- When function: Used to determine if a CSS variable should be treated as a font property
261
262
Default: `true`
263
264
**Function signature for CSS variables:**
265
266
```javascript { .api }
267
type RemoveQuotesFunction = (prop: string) => '' | 'font' | 'font-family' | 'font-weight';
268
```
269
270
The function receives a CSS property name and should return:
271
- `'font-family'`: Process as font-family property
272
- `'font-weight'`: Process as font-weight property
273
- `'font'`: Process as font shorthand property
274
- `''`: Don't process (preserve quotes)
275
276
## Safety Features
277
278
The plugin includes several safety mechanisms:
279
280
### Variable Function Detection
281
282
The plugin automatically skips processing when CSS variable functions (`var()`, `env()`) are detected in property values to avoid breaking dynamic values.
283
284
```css
285
/* These will not be processed */
286
h1 { font-family: var(--main-font), sans-serif; }
287
p { font-weight: env(--weight-normal); }
288
```
289
290
### Identifier Escaping
291
292
Font family names that contain special characters or start with invalid identifier patterns are properly escaped according to CSS specification.
293
294
### Keyword Preservation
295
296
Generic font family keywords and CSS global keywords (`inherit`, `initial`, `unset`) are preserved and never quoted.
297
298
## Performance
299
300
The plugin uses internal caching to avoid reprocessing identical property-value combinations, improving performance when processing large stylesheets with repeated font declarations.
301
302
## Types
303
304
```typescript { .api }
305
interface Options {
306
removeAfterKeyword?: boolean;
307
removeDuplicates?: boolean;
308
removeQuotes?: boolean | ((prop: string) => '' | 'font' | 'font-family' | 'font-weight');
309
}
310
311
interface Plugin {
312
postcssPlugin: 'postcss-minify-font-values';
313
prepare(): {
314
OnceExit(css: Root): void;
315
};
316
}
317
318
type RemoveQuotesFunction = (prop: string) => '' | 'font' | 'font-family' | 'font-weight';
319
```