0
# PostCSS Discard Empty
1
2
PostCSS Discard Empty is a PostCSS plugin that optimizes CSS by removing empty CSS constructs that do not affect the output. It automatically detects and discards empty rules, declarations without values, null selectors, and at-rules without content, helping reduce CSS bundle sizes while preserving functional styling.
3
4
## Package Information
5
6
- **Package Name**: postcss-discard-empty
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install postcss-discard-empty`
10
11
## Core Imports
12
13
```javascript
14
const discardEmpty = require('postcss-discard-empty');
15
```
16
17
For TypeScript/ESM:
18
```typescript
19
import discardEmpty from 'postcss-discard-empty';
20
```
21
22
CommonJS with destructuring:
23
```javascript
24
const { default: discardEmpty } = require('postcss-discard-empty');
25
```
26
27
## Basic Usage
28
29
```javascript
30
const postcss = require('postcss');
31
const discardEmpty = require('postcss-discard-empty');
32
33
const css = `
34
@font-face;
35
h1 {}
36
{color:blue}
37
h2 {color:}
38
h3 {color:red}
39
`;
40
41
postcss([discardEmpty()])
42
.process(css, { from: undefined })
43
.then(result => {
44
console.log(result.css);
45
// Output: h3 {color:red}
46
});
47
```
48
49
## Architecture
50
51
PostCSS Discard Empty follows the standard PostCSS plugin architecture:
52
53
- **Plugin Creator**: Main export function that returns a PostCSS plugin instance
54
- **Plugin Interface**: Implements PostCSS's `OnceExit` hook for processing CSS after all transformations
55
- **Processing Logic**: Recursively traverses CSS AST to identify and remove empty constructs
56
- **Message Reporting**: Reports each removed node via PostCSS's message system for debugging
57
58
## Capabilities
59
60
### Plugin Creation
61
62
Creates a PostCSS plugin instance for removing empty CSS constructs.
63
64
```javascript { .api }
65
/**
66
* Creates a PostCSS plugin that removes empty CSS rules, declarations, and at-rules
67
* @returns PostCSS plugin instance
68
*/
69
function pluginCreator(): import('postcss').Plugin;
70
```
71
72
The plugin creator function has no parameters and returns a PostCSS plugin that:
73
74
- Removes empty CSS rules (rules without selectors)
75
- Removes empty CSS declarations (declarations without values, except CSS custom properties starting with `--`)
76
- Removes null selectors (selectors that are empty strings)
77
- Removes empty at-rules (at-rules without parameters or child nodes, except `@layer` rules)
78
- Removes empty media queries and other container rules
79
80
**Usage Examples:**
81
82
```javascript
83
const postcss = require('postcss');
84
const discardEmpty = require('postcss-discard-empty');
85
86
// Use in PostCSS processing pipeline
87
const processor = postcss([discardEmpty()]);
88
89
// Process CSS with empty constructs
90
const result = await processor.process(`
91
@font-face; /* Empty at-rule - will be removed */
92
h1 {} /* Empty rule - will be removed */
93
{color:blue} /* Null selector - will be removed */
94
h2 {color:} /* Empty declaration - will be removed */
95
h3 {--custom:} /* Empty custom property - preserved */
96
h4 {color:red} /* Valid rule - preserved */
97
`, { from: undefined });
98
99
console.log(result.css);
100
// Output: h3 {--custom:} h4 {color:red}
101
```
102
103
### Plugin Compatibility Flag
104
105
PostCSS compatibility flag indicating this is a PostCSS plugin.
106
107
```javascript { .api }
108
/**
109
* PostCSS plugin compatibility flag
110
*/
111
pluginCreator.postcss: true;
112
```
113
114
This flag is required by PostCSS to identify the function as a valid plugin creator.
115
116
## Processing Behavior
117
118
The plugin processes CSS constructs in the following order:
119
120
1. **Empty At-rules**: Removes at-rules like `@font-face;` or `@media {}` with no content
121
2. **Empty Rules**: Removes CSS rules with no selector or empty selectors
122
3. **Empty Declarations**: Removes declarations without values, except CSS custom properties (variables starting with `--`)
123
4. **Special Cases**: Preserves empty `@layer` at-rules as they serve a functional purpose in CSS cascade layers
124
125
## Message Reporting
126
127
Each removed CSS construct generates a removal message with:
128
129
```javascript { .api }
130
interface RemovalMessage {
131
type: 'removal';
132
plugin: 'postcss-discard-empty';
133
node: import('postcss').AnyNode;
134
}
135
```
136
137
These messages can be accessed through the PostCSS result object for debugging or logging purposes.
138
139
## Build Tool Integration
140
141
### Webpack Configuration
142
143
```javascript
144
module.exports = {
145
module: {
146
rules: [
147
{
148
test: /\.css$/,
149
use: [
150
'style-loader',
151
'css-loader',
152
{
153
loader: 'postcss-loader',
154
options: {
155
postcssOptions: {
156
plugins: [
157
require('postcss-discard-empty')(),
158
],
159
},
160
},
161
},
162
],
163
},
164
],
165
},
166
};
167
```
168
169
### Vite Configuration
170
171
```javascript
172
// vite.config.js
173
import { defineConfig } from 'vite';
174
175
export default defineConfig({
176
css: {
177
postcss: {
178
plugins: [
179
require('postcss-discard-empty')(),
180
],
181
},
182
},
183
});
184
```
185
186
### PostCSS Configuration File
187
188
```javascript
189
// postcss.config.js
190
module.exports = {
191
plugins: [
192
require('postcss-discard-empty')(),
193
// other plugins...
194
],
195
};
196
```
197
198
## Types
199
200
```typescript { .api }
201
/**
202
* Main plugin creator function export
203
*/
204
declare function pluginCreator(): import('postcss').Plugin;
205
206
declare namespace pluginCreator {
207
/**
208
* PostCSS compatibility flag
209
*/
210
let postcss: true;
211
}
212
213
/**
214
* Plugin instance returned by the creator
215
*/
216
interface Plugin extends import('postcss').Plugin {
217
postcssPlugin: 'postcss-discard-empty';
218
OnceExit(css: import('postcss').Root, helpers: { result: import('postcss').Result }): void;
219
}
220
221
export = pluginCreator;
222
```