CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-cssnano

A modular minifier, built on top of the PostCSS ecosystem

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

CSSnano

A modular minifier, built on top of the PostCSS ecosystem. CSSnano takes CSS and compresses it through a configurable preset system, allowing you to choose the level of optimization that suits your needs.

Package Information

  • Package Name: cssnano
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install cssnano

Core Imports

const cssnano = require('cssnano');

For ES modules:

import cssnano from 'cssnano';

Basic Usage

const postcss = require('postcss');
const cssnano = require('cssnano');

// Basic usage with default preset
postcss([cssnano()])
  .process(css, { from: undefined })
  .then(result => {
    console.log(result.css);
  });

// With specific preset
postcss([cssnano({ preset: 'default' })])
  .process(css, { from: undefined })
  .then(result => {
    console.log(result.css);
  });

// With custom configuration
postcss([cssnano({
  preset: ['default', {
    discardComments: {
      removeAll: true,
    },
  }]
})])
  .process(css, { from: undefined })
  .then(result => {
    console.log(result.css);
  });

Architecture

CSSnano is built around a modular architecture with three key concepts:

  • Plugin Creator: The main cssnano function that creates PostCSS processors
  • Presets: Collections of optimization plugins configured for different use cases
  • Individual Plugins: Specific optimization transforms (postcss-minify-, postcss-normalize-, etc.)

The preset system allows loading cssnano in different configurations:

  • Default preset: Safe transforms with minimal assumptions
  • Advanced preset: More aggressive optimizations that may require specific browser support
  • Lite preset: Minimal optimizations focusing on whitespace and comments

Capabilities

Plugin Creator Function

Creates a PostCSS processor with the specified configuration options.

/**
 * Creates a PostCSS processor with cssnano optimizations
 * @param {Options} options - Configuration options
 * @returns {import('postcss').Processor} PostCSS processor instance
 */
function cssnano(options?: Options): import('postcss').Processor;

Configuration Options

interface Options {
  /** Preset configuration - can be string, array, function, or object */
  preset?: string | [string, any] | Function | { plugins: any[] };
  /** Additional plugins to include */
  plugins?: Array<string | Function | [string | Function, any]>;
  /** Path to configuration file */
  configFile?: string;
}

Built-in Presets

CSSnano includes three built-in presets:

Default Preset

Safe optimizations that make minimal assumptions about your CSS.

/**
 * Default preset with safe optimizations
 * @param {DefaultPresetOptions} options - Preset configuration
 * @returns {{ plugins: Array<[Function, any]> }} Plugin configuration
 */
function defaultPreset(options?: DefaultPresetOptions): { plugins: Array<[Function, any]> };

interface DefaultPresetOptions {
  /** CSS declaration sorting options */
  cssDeclarationSorter?: false | { keepOverrides?: boolean };
  /** Comment removal options */
  discardComments?: false | { removeAll?: boolean; remove?: Function };
  /** Initial value reduction options */
  reduceInitial?: false | any;
  /** Gradient minification options */
  minifyGradients?: false | any;
  /** SVG optimization options */
  svgo?: false | { plugins?: any[] };
  /** Transform reduction options */
  reduceTransforms?: false | any;
  /** Value conversion options */
  convertValues?: false | { length?: boolean };
  /** Calc() optimization options */
  calc?: false | any;
  /** Color minification options */
  colormin?: false | any;
  /** Ordered values optimization */
  orderedValues?: false | any;
  /** Selector minification options */
  minifySelectors?: false | { sort?: boolean };
  /** Parameter minification options */
  minifyParams?: false | any;
  /** Charset normalization options */
  normalizeCharset?: false | { add?: boolean };
  /** Font value minification options */
  minifyFontValues?: false | {
    removeAfterKeyword?: boolean;
    removeDuplicates?: boolean;
    removeQuotes?: boolean | Function;
  };
  /** URL normalization options */
  normalizeUrl?: false | any;
  /** Longhand merging options */
  mergeLonghand?: false | any;
  /** Duplicate removal options */
  discardDuplicates?: false | any;
  /** Overridden rule removal options */
  discardOverridden?: false | any;
  /** Repeat style normalization options */
  normalizeRepeatStyle?: false | any;
  /** Rule merging options */
  mergeRules?: false | any;
  /** Empty rule removal options */
  discardEmpty?: false | any;
  /** Selector deduplication options */
  uniqueSelectors?: false | any;
  /** String normalization options */
  normalizeString?: false | any;
  /** Position normalization options */
  normalizePositions?: false | any;
  /** Whitespace normalization options */
  normalizeWhitespace?: false | any;
  /** Unicode normalization options */
  normalizeUnicode?: false | any;
  /** Display value normalization options */
  normalizeDisplayValues?: false | any;
  /** Timing function normalization options */
  normalizeTimingFunctions?: false | any;
  /** Browserslist override */
  overrideBrowserslist?: string | string[];
}

Advanced Preset

More aggressive optimizations that may break CSS in some cases.

/**
 * Advanced preset with aggressive optimizations
 * @param {AdvancedPresetOptions} options - Preset configuration
 * @returns {{ plugins: Array<[Function, any]> }} Plugin configuration
 */
function advancedPreset(options?: AdvancedPresetOptions): { plugins: Array<[Function, any]> };

interface AdvancedPresetOptions extends DefaultPresetOptions {
  /** Autoprefixer options */
  autoprefixer?: {
    add?: boolean;
    overrideBrowserslist?: string | string[];
  };
  /** Unused rule discarding options */
  discardUnused?: false | any;
  /** Identifier merging options */
  mergeIdents?: false | any;
  /** Identifier reduction options */
  reduceIdents?: false | any;
  /** Z-index optimization options */
  zindex?: false | any;
}

Lite Preset

Minimal optimizations focusing on whitespace and comments.

/**
 * Lite preset with minimal optimizations
 * @param {LitePresetOptions} options - Preset configuration
 * @returns {{ plugins: Array<[Function, any]> }} Plugin configuration
 */
function litePreset(options?: LitePresetOptions): { plugins: Array<[Function, any]> };

interface LitePresetOptions {
  /** Comment removal options */
  discardComments?: false | { removeAll?: boolean };
  /** Whitespace normalization options */
  normalizeWhitespace?: false | any;
  /** Empty rule removal options */
  discardEmpty?: false | any;
  /** Raw cache options */
  rawCache?: false | any;
}

Configuration Loading

CSSnano supports multiple configuration methods:

/**
 * Configuration loading priority:
 * 1. Direct options parameter
 * 2. External configuration file
 * 3. Default preset
 * 
 * Supported configuration files:
 * - package.json (cssnano property)
 * - .cssnanorc
 * - .cssnanorc.json
 * - .cssnanorc.js
 * - cssnano.config.js
 */

PostCSS Integration

// Plugin has postcss flag for PostCSS compatibility
cssnano.postcss = true;

Common Integration Patterns:

// With PostCSS CLI
module.exports = {
  plugins: [
    require('cssnano')({
      preset: ['default', {
        discardComments: {
          removeAll: true,
        },
      }]
    })
  ]
};

// With webpack postcss-loader
module.exports = {
  module: {
    rules: [{
      test: /\.css$/,
      use: [
        'style-loader',
        'css-loader',
        {
          loader: 'postcss-loader',
          options: {
            plugins: [
              require('cssnano')({ preset: 'advanced' })
            ]
          }
        }
      ]
    }]
  }
};

// With Gulp
const gulp = require('gulp');
const postcss = require('gulp-postcss');

gulp.task('css', () => {
  return gulp.src('src/*.css')
    .pipe(postcss([
      require('cssnano')({
        preset: ['default', {
          minifyFontValues: {
            removeAfterKeyword: true
          }
        }]
      })
    ]))
    .pipe(gulp.dest('dist/'));
});

// Programmatic usage
const postcss = require('postcss');
const cssnano = require('cssnano');
const fs = require('fs');

const css = fs.readFileSync('input.css', 'utf8');

postcss([cssnano()])
  .process(css, { from: 'input.css', to: 'output.css' })
  .then(result => {
    fs.writeFileSync('output.css', result.css);
    if (result.map) {
      fs.writeFileSync('output.css.map', result.map.toString());
    }
  });

Error Handling

CSSnano safely handles:

  • Invalid CSS syntax - passes through unchanged
  • Unsupported CSS features - skips optimization
  • Configuration errors - throws descriptive error messages
  • Plugin loading failures - reports missing dependencies

Common errors:

  • Cannot load preset "${name}" - Invalid preset name or missing dependency
  • Configuration validation errors for invalid options

Optimization Overview

CSSnano performs various optimizations including:

  1. Whitespace & Comments: Remove unnecessary whitespace and comments
  2. Values: Minify colors, fonts, gradients, and other CSS values
  3. Selectors: Deduplicate and optimize CSS selectors
  4. Rules: Merge compatible rules and remove duplicates
  5. Properties: Merge longhand properties and remove overridden declarations
  6. Advanced: Identifier reduction, z-index optimization (advanced preset only)

Input Example:

/* This is a comment */
h1 {
  font-weight: bold;
  font-family: "Helvetica Neue", Arial, sans-serif;
  color: #ff0000;
  margin: 10px 10px 10px 10px;
}

h1 {
  padding: 0px;
}

Output (default preset):

h1{font-weight:700;font-family:Helvetica Neue,Arial,sans-serif;color:red;margin:10px;padding:0}

docs

index.md

tile.json