postcss-merge-longhand

postcss-merge-longhand is a PostCSS plugin that optimizes CSS by merging longhand properties into their shorthand equivalents. It automatically combines related longhand properties (like margin-top, margin-right, margin-bottom, margin-left) into concise shorthand declarations (like margin: 10px 20px) when possible, reducing file size and improving performance.

Package Information

• Package Name: postcss-merge-longhand
• Package Type: npm
• Language: JavaScript
• Installation: npm install postcss-merge-longhand postcss

Core Imports

const plugin = require("postcss-merge-longhand");

For ES modules:

import plugin from "postcss-merge-longhand";

Basic Usage

const postcss = require("postcss");
const mergeLonghand = require("postcss-merge-longhand");

// Create PostCSS processor with the plugin
const processor = postcss([mergeLonghand()]);

// Process CSS
const result = processor.process(`
  h1 {
    margin-top: 10px;
    margin-right: 20px;
    margin-bottom: 10px;
    margin-left: 20px;
  }
`);

// Output: h1 { margin: 10px 20px; }
console.log(result.css);

Capabilities

Plugin Creator Function

Creates a PostCSS plugin instance that merges longhand properties into shorthand equivalents.

/**
 * Creates a PostCSS plugin instance for merging longhand properties
 * @returns {Plugin} PostCSS plugin object
 */
function pluginCreator(): Plugin;

/** Plugin creator has postcss property set to true */
pluginCreator.postcss: true;

Plugin Object

The PostCSS plugin object returned by the plugin creator.

interface Plugin {
  /** Plugin name identifier */
  postcssPlugin: "postcss-merge-longhand";
  /** Processing function that runs once after CSS parsing */
  OnceExit(css: PostCSSRoot): void;
}

interface PostCSSRoot {
  /** Walk through all rules in the CSS AST */
  walkRules(callback: (rule: PostCSSRule) => void): void;
}

interface PostCSSRule {
  /** Walk through all declarations in this rule */
  walkDecls(callback: (decl: PostCSSDeclaration) => void): void;
  /** Walk through declarations matching a property pattern */
  walkDecls(prop: RegExp | string, callback: (decl: PostCSSDeclaration) => void): void;
}

interface PostCSSDeclaration {
  /** CSS property name */
  prop: string;
  /** CSS property value */
  value: string;
  /** Whether the declaration is marked as !important */
  important: boolean;
  /** Parent rule or at-rule */
  parent: PostCSSRule | null;
  /** Remove this declaration from its parent */
  remove(): void;
}

Supported Property Groups

The plugin processes these CSS property groups:

Margin Properties

• margin - Margin shorthand
• margin-top, margin-right, margin-bottom, margin-left - Directional margins

Padding Properties

• padding - Padding shorthand
• padding-top, padding-right, padding-bottom, padding-left - Directional padding

Border Properties

• border - General border shorthand (width, style, color)
• border-top, border-right, border-bottom, border-left - Directional borders
• border-width, border-style, border-color - Border aspect shorthands
• border-top-width, border-right-width, border-bottom-width, border-left-width - Directional border widths
• border-top-style, border-right-style, border-bottom-style, border-left-style - Directional border styles
• border-top-color, border-right-color, border-bottom-color, border-left-color - Directional border colors
• border-spacing - Table border spacing (also minified when appropriate)

Column Properties

• columns - Columns shorthand
• column-width, column-count - Column longhand properties

Usage Examples

Basic Margin Merging

Input CSS:

.box {
  margin-top: 10px;
  margin-right: 15px;
  margin-bottom: 10px;  
  margin-left: 15px;
}

Output CSS:

.box {
  margin: 10px 15px;
}

Border Property Optimization

Input CSS:

.card {
  border-top-width: 2px;
  border-right-width: 2px;
  border-bottom-width: 2px;
  border-left-width: 2px;
  border-top-style: solid;
  border-right-style: solid;
  border-bottom-style: solid;
  border-left-style: solid;
  border-top-color: red;
  border-right-color: red;
  border-bottom-color: red;
  border-left-color: red;
}

Output CSS:

.card {
  border: 2px solid red;
}

Column Property Merging

Input CSS:

.layout {
  column-width: 200px;
  column-count: 3;
}

Output CSS:

.layout {
  columns: 200px 3;
}

Integration with PostCSS

const postcss = require("postcss");
const mergeLonghand = require("postcss-merge-longhand");
const autoprefixer = require("autoprefixer");

// Use with other PostCSS plugins
const processor = postcss([
  autoprefixer(),
  mergeLonghand(),
  // Add other optimization plugins
]);

processor.process(cssString, { from: undefined })
  .then(result => {
    console.log(result.css);
  });

Build Tool Integration

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [
                  require("postcss-merge-longhand")(),
                ]
              }
            }
          }
        ]
      }
    ]
  }
};

Optimization Behavior

The plugin performs several types of optimizations:

1. Directional Property Merging: Combines directional properties (top, right, bottom, left) into shorthand when values allow for compression
2. Duplicate Removal: Removes duplicate and redundant property declarations
3. Value Minimization: Shortens property values using standard CSS shorthand rules
4. Precedence Handling: Respects CSS cascade and specificity rules
5. Style Hack Detection: Preserves CSS hacks and browser-specific workarounds

Dependencies

This plugin requires PostCSS as a peer dependency:

{
  "peerDependencies": {
    "postcss": "^8.4.32"
  }
}

Internal dependencies:

• postcss-value-parser - For parsing and manipulating CSS values
• stylehacks - For detecting and preserving CSS hacks

Error Handling

The plugin gracefully handles various edge cases:

• Invalid CSS values: Malformed or unparseable values are preserved as-is
• Mixed importance levels: Properties with different !important declarations are not merged
• Style hacks: Browser-specific CSS hacks are detected and preserved
• Custom properties: CSS variables are preserved and not processed
• Incomplete property sets: Partial longhand property sets are only merged when safe

Limitations

• Preserves CSS custom properties (CSS variables) and doesn't merge properties containing them
• Respects !important declarations and doesn't merge properties with different importance levels
• Maintains browser-specific style hacks and doesn't optimize them away
• Only merges properties within the same CSS rule - doesn't merge across different selectors
• Requires PostCSS version 8.4.32 or higher
• Does not process properties inside CSS-in-JS template literals or other non-standard CSS contexts