or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-postcss-discard-comments

Discard comments in your CSS files with PostCSS.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/postcss-discard-comments@7.0.x

To install, run

npx @tessl/cli install tessl/npm-postcss-discard-comments@7.0.0

index.mddocs/

PostCSS Discard Comments

PostCSS Discard Comments is a sophisticated PostCSS plugin that removes comments from CSS files with granular control. It offers options to preserve important comments (marked with /*!), remove all comments including important ones, or use custom removal logic through a callback function. The plugin efficiently processes CSS syntax including selectors, declarations, at-rules, and their raw spacing while maintaining proper formatting.

Package Information

  • Package Name: postcss-discard-comments
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install postcss-discard-comments
  • Peer Dependencies: Requires PostCSS ^8.4.32

Core Imports

const postcssDiscardComments = require("postcss-discard-comments");

For ES modules:

import postcssDiscardComments from "postcss-discard-comments";

Basic Usage

const postcss = require("postcss");
const discardComments = require("postcss-discard-comments");

// Basic usage - removes regular comments, preserves /*! important */ comments
const result = await postcss([discardComments()])
  .process('h1/* heading */{margin: 0 auto}/*! important */', { from: undefined });

console.log(result.css);
// Output: h1 {margin: 0 auto}/*! important */

Architecture

PostCSS Discard Comments is built around several key components:

  • Plugin Creator: Main function that returns a PostCSS plugin instance configured with the provided options
  • Comment Remover: Internal class that implements the logic for determining which comments should be removed based on configuration
  • Comment Parser: Internal utility that tokenizes CSS text to identify comment boundaries and content
  • Multi-Context Processing: Processes comments across different CSS contexts including top-level comments, selector comments (using postcss-selector-parser), declaration values, at-rule parameters, and raw spacing
  • Performance Optimization: Uses caching mechanisms (matcherCache, replacerCache) to avoid reprocessing identical patterns

The plugin operates during PostCSS's OnceExit phase, walking the entire CSS AST and applying comment removal logic to each node type while preserving proper formatting.

Capabilities

Plugin Creator Function

The main export is a plugin creator function that returns a PostCSS plugin instance configured with the provided options.

/**
 * Creates a PostCSS plugin for removing comments from CSS
 * @param {Options} opts - Configuration options for comment removal
 * @returns {Plugin} PostCSS plugin instance with postcssPlugin: 'postcss-discard-comments'
 */
function postcssDiscardComments(opts = {}): Plugin;

Usage Examples:

// Default behavior - preserve important comments
const plugin1 = postcssDiscardComments();

// Remove all comments including important ones
const plugin2 = postcssDiscardComments({ removeAll: true });

// Keep only the first important comment
const plugin3 = postcssDiscardComments({ removeAllButFirst: true });

// Custom removal logic
const plugin4 = postcssDiscardComments({
  remove: function(comment) {
    return comment.startsWith('@'); // Remove comments starting with @
  }
});

Comment Removal Options

The plugin accepts an options object to control comment removal behavior.

/**
 * Configuration options for comment removal
 * @typedef {Object} Options
 * @property {boolean} [removeAll] - Remove all comments including important ones
 * @property {boolean} [removeAllButFirst] - Remove all important comments except the first
 * @property {function} [remove] - Custom function to determine comment removal
 */
interface Options {
  /** Remove all comments including important ones marked with /*! */
  removeAll?: boolean;
  /** Remove all important comments except the first one encountered */
  removeAllButFirst?: boolean;
  /** Custom function to determine if a comment should be removed
   * @param comment - Comment text without /* and */ delimiters
   * @returns true to remove the comment, false to keep it
   */
  remove?: (comment: string) => boolean;
}

Option Details:

  • removeAll: When true, removes all comments including those marked as important with /*!
  • removeAllButFirst: When true, preserves only the first important comment encountered and removes all others
  • remove: Custom function that receives the comment text (without /* and */) and returns a boolean. If provided, other options are ignored.

Usage Examples:

// Remove all comments
const css1 = '/*! license */h1/* heading */{margin: 0}';
const result1 = postcss([discardComments({ removeAll: true })])
  .process(css1, { from: undefined });
// Output: h1{margin: 0}

// Keep only first important comment
const css2 = '/*! license */h1{margin: 0}/*! author */';
const result2 = postcss([discardComments({ removeAllButFirst: true })])
  .process(css2, { from: undefined });
// Output: /*! license */h1{margin: 0}

// Custom removal logic
const css3 = '/*@ remove this */h1/* keep this */{margin: 0}';
const result3 = postcss([discardComments({
  remove: function(comment) { return comment.startsWith('@'); }
})])
  .process(css3, { from: undefined });
// Output: h1/* keep this */{margin: 0}

Plugin Properties

The plugin function includes a static property for PostCSS compatibility.

/** PostCSS plugin marker property */
postcssDiscardComments.postcss = true;

Processing Behavior

The plugin processes CSS comments in various contexts:

  • Top-level comments: Direct comment nodes in the CSS AST
  • Selector comments: Comments within CSS selectors using postcss-selector-parser
  • Declaration comments: Comments in property values and !important declarations
  • At-rule comments: Comments in at-rule parameters and spacing
  • Raw spacing: Comments in the raw spacing between CSS nodes

The plugin uses caching mechanisms (matcherCache, replacerCache) for performance optimization when processing repeated patterns.

Integration

This plugin is designed for use in CSS build pipelines and optimization workflows. It integrates seamlessly with other PostCSS plugins and is commonly used in production builds where comment removal is desired to reduce file size while preserving critical license or attribution comments when needed.

// Example build configuration
const postcss = require("postcss");
const discardComments = require("postcss-discard-comments");
const cssnano = require("cssnano");

const processor = postcss([
  discardComments({ removeAllButFirst: true }), // Keep first license comment
  cssnano() // Further optimization
]);