0
# UglifyCSS
1

2
UglifyCSS is a port of YUI CSS Compressor to NodeJS for CSS minification and compression. It applies multiple regex-based optimizations to reduce CSS file sizes while maintaining functionality, supporting features like variable expansion, comment handling, URL conversion, and configurable line length limits.
3

4
## Package Information
5

6
- **Package Name**: uglifycss
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install uglifycss`
10
- **Command Line**: `npm install uglifycss -g`
11

12
## Core Imports
13

14
```javascript
15
const { processString, processFiles, defaultOptions } = require('uglifycss');
16
```
17

18
For ESM environments (with appropriate tooling like Babel or Node.js with experimental support):
19

20
```javascript
21
import uglifycss from 'uglifycss';
22
const { processString, processFiles, defaultOptions } = uglifycss;
23
```
24

25
## Basic Usage
26

27
### Process a CSS String
28

29
```javascript
30
const uglifycss = require('uglifycss');
31

32
const css = `
33
body {
34
    margin: 0px;
35
    padding: 0px;
36
    background-color: #ffffff;
37
}
38
`;
39

40
const minified = uglifycss.processString(css);
41
console.log(minified);
42
// Output: body{margin:0;padding:0;background-color:#fff}
43
```
44

45
### Process CSS Files
46

47
```javascript
48
const uglifycss = require('uglifycss');
49

50
const minified = uglifycss.processFiles(['styles.css', 'theme.css'], {
51
    maxLineLen: 500,
52
    expandVars: true
53
});
54

55
console.log(minified);
56
```
57

58
### Command Line Usage
59

60
```bash
61
# Process single file
62
uglifycss input.css > output.css
63

64
# Process multiple files
65
uglifycss file1.css file2.css > combined.css
66

67
# With options
68
uglifycss --max-line-len 80 --expand-vars input.css > output.css
69

70
# Output to file
71
uglifycss --output minified.css input.css
72
```
73

74
## Capabilities
75

76
### String Processing
77

78
Processes a CSS string and returns the minified result.
79

80
```javascript { .api }
81
/**
82
 * Uglifies a CSS string
83
 * @param {string} [content=''] - CSS string to process
84
 * @param {Options} [options=defaultOptions] - UglifyCSS options
85
 * @returns {string} Uglified CSS result
86
 */
87
function processString(content, options);
88
```
89

90
### File Processing
91

92
Processes multiple CSS files, concatenates them, and returns the minified result.
93

94
```javascript { .api }
95
/**
96
 * Uglifies a set of CSS files
97
 * @param {string[]} [filenames=[]] - Array of CSS filenames to process
98
 * @param {Options} [options=defaultOptions] - UglifyCSS options
99
 * @returns {string} Concatenated and uglified CSS result
100
 */
101
function processFiles(filenames, options);
102
```
103

104
### Default Options
105

106
Configuration object containing default processing options.
107

108
```javascript { .api }
109
/**
110
 * Default configuration options
111
 * @type {Options}
112
 */
113
const defaultOptions = {
114
    maxLineLen: 0,
115
    expandVars: false,
116
    uglyComments: false,
117
    cuteComments: false,
118
    convertUrls: '',
119
    debug: false,
120
    output: ''
121
};
122
```
123

124
## Types
125

126
```javascript { .api }
127
/**
128
 * UglifyCSS configuration options
129
 * @typedef {Object} Options
130
 * @property {number} maxLineLen - Maximum line length of uglified CSS (0 means no newline)
131
 * @property {boolean} expandVars - Expand @variables blocks and var() references
132
 * @property {boolean} uglyComments - Remove newlines within preserved comments
133
 * @property {boolean} cuteComments - Preserve newlines within and around preserved comments
134
 * @property {string} convertUrls - Convert relative URLs using the given directory as location target
135
 * @property {boolean} debug - Print full error stack on error
136
 * @property {string} output - Output file name (CLI only)
137
 */
138
```
139

140
## Configuration Options
141

142
### maxLineLen
143
- **Type**: `number`
144
- **Default**: `0`
145
- **Description**: Adds a newline approximately every n characters. 0 means no newline.
146

147
### expandVars
148
- **Type**: `boolean`  
149
- **Default**: `false`
150
- **Description**: Expands `@variables` blocks and replaces `var(x)` references with their values.
151

152
### uglyComments
153
- **Type**: `boolean`
154
- **Default**: `false`
155
- **Description**: Removes newlines within preserved comments (comments starting with `/*!`).
156

157
### cuteComments
158
- **Type**: `boolean`
159
- **Default**: `false`
160
- **Description**: Preserves newlines within and around preserved comments.
161

162
### convertUrls
163
- **Type**: `string`
164
- **Default**: `''`
165
- **Description**: Converts relative URLs using the specified directory as the location target.
166

167
### debug
168
- **Type**: `boolean`
169
- **Default**: `false`
170
- **Description**: Prints full error stack on error instead of simple error message.
171

172
### output
173
- **Type**: `string`
174
- **Default**: `''`
175
- **Description**: Output file name (used by CLI only).
176

177
## Command Line Interface
178

179
The `uglifycss` command provides access to all functionality via command line:
180

181
```bash
182
uglifycss [options] file1.css [file2.css [...]] > output
183
```
184

185
The CLI can also process CSS from stdin when no files are specified. Note that stdin input is not compatible with the `--convert-urls` option.
186

187
### CLI Options
188

189
- `--max-line-len n` - Add newline every n characters
190
- `--expand-vars` - Expand variables  
191
- `--ugly-comments` - Remove newlines within preserved comments
192
- `--cute-comments` - Preserve newlines within and around comments
193
- `--convert-urls d` - Convert relative URLs using directory d as target
194
- `--debug` - Print full error stack on error
195
- `--output f` - Put result in file f
196
- `--help` - Show help message
197
- `--version` - Display version number
198

199
### CLI Examples
200

201
```bash
202
# Basic minification
203
uglifycss styles.css > minified.css
204

205
# Multiple files with options
206
uglifycss --max-line-len 80 --expand-vars style1.css style2.css > combined.css
207

208
# Convert relative URLs and output to file
209
uglifycss --convert-urls ./build --output dist/styles.css src/styles.css
210

211
# Process from stdin (not compatible with --convert-urls)
212
cat styles.css | uglifycss > minified.css
213
echo "body{margin:0}" | uglifycss
214
```
215

216
## Advanced Usage
217

218
### Variable Expansion
219

220
```javascript
221
const css = `
222
@variables {
223
    primary-color: #3498db;
224
    margin-size: 10px;
225
}
226

227
.header {
228
    color: var(primary-color);
229
    margin: var(margin-size);
230
}
231
`;
232

233
const minified = uglifycss.processString(css, { expandVars: true });
234
// Variables are expanded and @variables block is removed
235
```
236

237
### URL Conversion
238

239
```javascript
240
const options = {
241
    convertUrls: '/build',
242
    source: ['/src/css'],  // Set internally by processFiles
243
    target: ['/build']     // Set internally based on convertUrls
244
};
245

246
// Relative URLs in CSS files will be converted based on the target directory
247
const minified = uglifycss.processFiles(['src/css/styles.css'], options);
248
```
249

250
### Comment Handling
251

252
```javascript
253
const css = `
254
/* Regular comment - will be removed */
255
/*! Important comment - will be preserved */
256
body {
257
    margin: 0;
258
}
259
`;
260

261
// Default behavior - preserves important comments
262
const minified1 = uglifycss.processString(css);
263

264
// Remove newlines in preserved comments
265
const minified2 = uglifycss.processString(css, { uglyComments: true });
266

267
// Preserve newlines in preserved comments
268
const minified3 = uglifycss.processString(css, { cuteComments: true });
269
```
270

271
### Line Length Control
272

273
```javascript
274
const css = 'body{margin:0;padding:0;background:#fff;color:#000;font-size:16px;line-height:1.5;}';
275

276
// Add newlines every 50 characters
277
const formatted = uglifycss.processString(css, { maxLineLen: 50 });
278
```
279

280
## Error Handling
281

282
UglifyCSS will exit with status code 1 if it encounters file processing errors. Use the `debug` option for detailed error information:
283

284
```javascript
285
try {
286
    const result = uglifycss.processFiles(['nonexistent.css'], { debug: true });
287
} catch (error) {
288
    // Error details will be logged to console
289
    // Process will exit with code 1
290
}
291
```
292

293
## CSS Optimizations Applied
294

295
UglifyCSS applies numerous optimizations including:
296

297
- Removing unnecessary whitespace and comments
298
- Compressing hex colors (#AABBCC → #ABC)
299
- Converting rgb() to hex when shorter
300
- Removing unnecessary units (0px → 0)
301
- Shortening color keywords (#ff0000 → red)
302
- Optimizing border and background declarations
303
- Preserving IE hacks and browser-specific syntax
304
- Handling data URLs and preserving Base64 content
305
- Normalizing @charset and @import declarations