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
```