0
# Less Plugin Clean CSS
1

2
Less Plugin Clean CSS is a Less.js plugin that integrates the clean-css library for CSS minification and optimization. It enables developers to compress CSS output from Less compilation by applying advanced optimizations including whitespace removal, property merging, selector optimization, and dead code elimination.
3

4
## Package Information
5

6
- **Package Name**: less-plugin-clean-css
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install less-plugin-clean-css`
10

11
## Core Imports
12

13
```javascript
14
const LessPluginCleanCSS = require('less-plugin-clean-css');
15
```
16

17
## Basic Usage
18

19
### Programmatic Usage
20

21
```javascript
22
const less = require('less');
23
const LessPluginCleanCSS = require('less-plugin-clean-css');
24

25
// Create plugin instance with options
26
const cleanCSSPlugin = new LessPluginCleanCSS({
27
  advanced: true,
28
  keepSpecialComments: 1,
29
  compatibility: 'ie8'
30
});
31

32
// Use with Less.js
33
less.render(lessString, { plugins: [cleanCSSPlugin] })
34
  .then(result => {
35
    console.log(result.css); // Minified CSS output
36
  });
37
```
38

39
### Command Line Usage
40

41
```bash
42
# Install Less.js globally
43
npm install -g less
44

45
# Install the plugin globally
46
npm install -g less-plugin-clean-css
47

48
# Use with lessc
49
lessc input.less --clean-css="--s1 --advanced --compatibility=ie8"
50
```
51

52
## Architecture
53

54
The plugin follows the Less.js plugin architecture with these key components:
55

56
- **Main Plugin Class**: `LessPluginCleanCSS` - Entry point and configuration management
57
- **Processor Integration**: Registers a post-processor that runs after Less compilation
58
- **Options Parsing**: Flexible configuration supporting both object and string formats
59
- **Clean-CSS Integration**: Uses clean-css library for actual CSS minification
60

61
## Capabilities
62

63
### Plugin Constructor
64

65
Creates a new Less.js plugin instance for CSS minification.
66

67
```javascript { .api }
68
/**
69
 * Creates a Less.js plugin instance for CSS minification
70
 * @param {Object|String} options - Configuration options for clean-css
71
 */
72
function LessPluginCleanCSS(options);
73
```
74

75
### Plugin Installation
76

77
Registers the plugin with Less.js to enable CSS minification during compilation.
78

79
```javascript { .api }
80
/**
81
 * Registers the plugin with Less.js plugin manager
82
 * @param {Object} less - Less.js instance
83
 * @param {Object} pluginManager - Less.js plugin manager
84
 */
85
LessPluginCleanCSS.prototype.install = function(less, pluginManager);
86
```
87

88
### Usage Information
89

90
Prints detailed usage information and available options to the console.
91

92
```javascript { .api }
93
/**
94
 * Prints usage information for the plugin to console
95
 */
96
LessPluginCleanCSS.prototype.printUsage = function();
97
```
98

99
### Options Configuration
100

101
Updates plugin configuration after instantiation.
102

103
```javascript { .api }
104
/**
105
 * Updates plugin options after instantiation
106
 * @param {Object|String} options - New configuration options
107
 */
108
LessPluginCleanCSS.prototype.setOptions = function(options);
109
```
110

111
### Minimum Version Requirement
112

113
Specifies the minimum required Less.js version for compatibility.
114

115
```javascript { .api }
116
/**
117
 * Minimum required Less.js version [2, 1, 0]
118
 * @type {Array<number>}
119
 */
120
LessPluginCleanCSS.prototype.minVersion = [2, 1, 0];
121
```
122

123
## Configuration Options
124

125
The plugin supports all clean-css options with some defaults optimized for Less.js output:
126

127
### String Format Options
128

129
When using string format (command-line), options are space-separated:
130

131
- `keep-line-breaks` or `b` - Preserve line breaks in output
132
- `s0` - Remove all special comments
133
- `s1` - Keep first special comment only
134
- `keepSpecialComments=*` - Keep all special comments (default)
135
- `advanced` - Enable advanced optimizations (default: false)
136
- `rebase` - Enable URL rebasing (default: false)
137
- `compatibility=ie8` - Set CSS compatibility mode
138
- `rounding-precision=2` - Set decimal precision for numbers
139
- `skip-aggressive-merging` - Disable aggressive property merging
140
- `skip-restructuring` - Disable CSS restructuring
141
- `skip-shorthand-compacting` - Disable shorthand property compacting
142

143
### Object Format Options
144

145
When using object format (programmatic), use clean-css option names:
146

147
```javascript { .api }
148
interface CleanCSSOptions {
149
  /** Keep special comments: "*" (all), 1 (first), 0 (none) */
150
  keepSpecialComments?: string | number;
151
  /** Enable advanced optimizations */
152
  advanced?: boolean;
153
  /** Enable URL rebasing */
154
  rebase?: boolean;
155
  /** Preserve line breaks */
156
  keepBreaks?: boolean;
157
  /** CSS compatibility mode */
158
  compatibility?: string;
159
  /** Decimal precision */
160
  roundingPrecision?: number;
161
  /** Enable aggressive property merging */
162
  aggressiveMerging?: boolean;
163
  /** Enable CSS restructuring */
164
  restructuring?: boolean;
165
  /** Enable shorthand property compacting */
166
  shorthandCompacting?: boolean;
167
}
168
```
169

170
**Usage Examples:**
171

172
```javascript
173
// Object format
174
const plugin = new LessPluginCleanCSS({
175
  advanced: true,
176
  keepSpecialComments: 1,
177
  compatibility: 'ie8',
178
  roundingPrecision: 2
179
});
180

181
// String format (parsed internally)  
182
const plugin2 = new LessPluginCleanCSS('s1 advanced compatibility=ie8 rounding-precision=2');
183
```
184

185
## Default Behavior
186

187
The plugin applies these defaults different from clean-css:
188

189
- `keepSpecialComments: "*"` - Keeps all special comments by default
190
- `processImport: false` - Disabled to avoid conflicts with Less imports
191
- `rebase: false` - Disabled by default for safety
192
- `advanced: false` - Disabled by default for safety
193

194
## Error Handling
195

196
The plugin throws errors for:
197

198
- **Invalid Options**: Unknown option names in string format
199
- **Parse Errors**: Malformed option strings
200
- **Clean-CSS Errors**: Underlying CSS processing failures
201

202
## Integration Examples
203

204
### With Build Tools
205

206
```javascript
207
// Webpack with less-loader
208
module.exports = {
209
  module: {
210
    rules: [{
211
      test: /\.less$/,
212
      use: [{
213
        loader: 'style-loader'
214
      }, {
215
        loader: 'css-loader'
216
      }, {
217
        loader: 'less-loader',
218
        options: {
219
          lessOptions: {
220
            plugins: [
221
              new (require('less-plugin-clean-css'))({ advanced: true })
222
            ]
223
          }
224
        }
225
      }]
226
    }]
227
  }
228
};
229
```
230

231
### With Express.js
232

233
```javascript
234
const express = require('express');
235
const less = require('less');
236
const LessPluginCleanCSS = require('less-plugin-clean-css');
237

238
app.get('/styles.css', async (req, res) => {
239
  const lessContent = await fs.readFile('styles.less', 'utf8');
240
  const result = await less.render(lessContent, {
241
    plugins: [new LessPluginCleanCSS({ advanced: true })]
242
  });
243
  res.type('text/css').send(result.css);
244
});
245
```