PostCSS Discard Duplicates

PostCSS Discard Duplicates is a PostCSS plugin that removes duplicate rules, declarations, and at-rules from CSS stylesheets to optimize file size. It provides intelligent deduplication by comparing node types, selectors, properties, values, and importance flags while preserving the semantic structure of CSS.

Package Information

• Package Name: postcss-discard-duplicates
• Package Type: npm
• Language: JavaScript
• Installation: npm install postcss-discard-duplicates
• Peer Dependencies: postcss ^8.4.31
• Node.js: ^14 || ^16 || >=18.0

Core Imports

const postcssDiscardDuplicates = require("postcss-discard-duplicates");

For ES modules (using TypeScript-style import):

import postcssDiscardDuplicates = require("postcss-discard-duplicates");

Or with modern ES module syntax:

import postcssDiscardDuplicates from "postcss-discard-duplicates";

Basic Usage

const postcss = require("postcss");
const postcssDiscardDuplicates = require("postcss-discard-duplicates");

// Using PostCSS directly
const result = await postcss([
  postcssDiscardDuplicates()
])
  .process(css, { from: "input.css", to: "output.css" });

console.log(result.css);

Example transformation:

Input CSS:

h1 {
  margin: 0 auto;
  margin: 0 auto
}

h1 {
  margin: 0 auto
}

Output CSS:

h1 {
  margin: 0 auto
}

Capabilities

Plugin Creator Function

Creates a PostCSS plugin instance that removes duplicate CSS constructs.

/**
 * Creates a PostCSS plugin that removes duplicate rules, declarations, and at-rules
 * @returns {import('postcss').Plugin} PostCSS plugin object
 */
function postcssDiscardDuplicates(): import('postcss').Plugin;

The plugin works by:

• Rules: Removes duplicate rules with identical selectors
• Declarations: Removes duplicate property-value pairs within rules
• At-rules: Removes duplicate at-rules with identical names and parameters
• Recursive Processing: Works through nested structures like media queries
• Preservation: Maintains CSS semantic structure and ordering

Plugin Properties

/**
 * PostCSS plugin compatibility flag
 */
postcssDiscardDuplicates.postcss: true;

Types

interface Plugin {
  postcssPlugin: string;
  OnceExit(root: import('postcss').Root): void;
}

Deduplication Behavior

The plugin removes duplicates based on exact matching:

• Rules: Same selector text
• Declarations: Same property name, value, and importance (!important)
• At-rules: Same name and parameters
• Whitespace: Raw whitespace values are normalized during comparison
• Comments: Comments are preserved and do not affect deduplication

Processing Order

1. Processes CSS AST from bottom-up (last to first)
2. For each rule, checks preceding rules for duplicates
3. For duplicate rules, merges declarations and removes empty rules
4. For duplicate declarations and at-rules, removes earlier instances
5. Recursively processes nested structures

Limitations

The plugin does not normalize:

• Selector order (e.g., h1, h2 vs h2, h1 are considered different)
• Declaration values (e.g., margin: 10px 0 10px 0 vs margin: 10px 0)
• Whitespace variations beyond raw value trimming

Error Handling

The plugin operates on the PostCSS AST and does not throw exceptions during normal operation. Invalid CSS should be handled by PostCSS parsing before the plugin runs.

Performance

The plugin uses efficient node comparison algorithms and processes the CSS tree recursively. Performance scales with the number of duplicate constructs rather than total CSS size.