or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-uglifycss

Port of YUI CSS Compressor to NodeJS for CSS minification and compression

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/uglifycss@0.0.x

To install, run

npx @tessl/cli install tessl/npm-uglifycss@0.0.0

index.mddocs/

UglifyCSS

UglifyCSS is a port of YUI CSS Compressor to NodeJS for CSS minification and compression. It applies multiple regex-based optimizations to reduce CSS file sizes while maintaining functionality, supporting features like variable expansion, comment handling, URL conversion, and configurable line length limits.

Package Information

  • Package Name: uglifycss
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install uglifycss
  • Command Line: npm install uglifycss -g

Core Imports

const { processString, processFiles, defaultOptions } = require('uglifycss');

For ESM environments (with appropriate tooling like Babel or Node.js with experimental support):

import uglifycss from 'uglifycss';
const { processString, processFiles, defaultOptions } = uglifycss;

Basic Usage

Process a CSS String

const uglifycss = require('uglifycss');

const css = `
body {
    margin: 0px;
    padding: 0px;
    background-color: #ffffff;
}
`;

const minified = uglifycss.processString(css);
console.log(minified);
// Output: body{margin:0;padding:0;background-color:#fff}

Process CSS Files

const uglifycss = require('uglifycss');

const minified = uglifycss.processFiles(['styles.css', 'theme.css'], {
    maxLineLen: 500,
    expandVars: true
});

console.log(minified);

Command Line Usage

# Process single file
uglifycss input.css > output.css

# Process multiple files
uglifycss file1.css file2.css > combined.css

# With options
uglifycss --max-line-len 80 --expand-vars input.css > output.css

# Output to file
uglifycss --output minified.css input.css

Capabilities

String Processing

Processes a CSS string and returns the minified result.

/**
 * Uglifies a CSS string
 * @param {string} [content=''] - CSS string to process
 * @param {Options} [options=defaultOptions] - UglifyCSS options
 * @returns {string} Uglified CSS result
 */
function processString(content, options);

File Processing

Processes multiple CSS files, concatenates them, and returns the minified result.

/**
 * Uglifies a set of CSS files
 * @param {string[]} [filenames=[]] - Array of CSS filenames to process
 * @param {Options} [options=defaultOptions] - UglifyCSS options
 * @returns {string} Concatenated and uglified CSS result
 */
function processFiles(filenames, options);

Default Options

Configuration object containing default processing options.

/**
 * Default configuration options
 * @type {Options}
 */
const defaultOptions = {
    maxLineLen: 0,
    expandVars: false,
    uglyComments: false,
    cuteComments: false,
    convertUrls: '',
    debug: false,
    output: ''
};

Types

/**
 * UglifyCSS configuration options
 * @typedef {Object} Options
 * @property {number} maxLineLen - Maximum line length of uglified CSS (0 means no newline)
 * @property {boolean} expandVars - Expand @variables blocks and var() references
 * @property {boolean} uglyComments - Remove newlines within preserved comments
 * @property {boolean} cuteComments - Preserve newlines within and around preserved comments
 * @property {string} convertUrls - Convert relative URLs using the given directory as location target
 * @property {boolean} debug - Print full error stack on error
 * @property {string} output - Output file name (CLI only)
 */

Configuration Options

maxLineLen

  • Type: number
  • Default: 0
  • Description: Adds a newline approximately every n characters. 0 means no newline.

expandVars

  • Type: boolean
  • Default: false
  • Description: Expands @variables blocks and replaces var(x) references with their values.

uglyComments

  • Type: boolean
  • Default: false
  • Description: Removes newlines within preserved comments (comments starting with /*!).

cuteComments

  • Type: boolean
  • Default: false
  • Description: Preserves newlines within and around preserved comments.

convertUrls

  • Type: string
  • Default: ''
  • Description: Converts relative URLs using the specified directory as the location target.

debug

  • Type: boolean
  • Default: false
  • Description: Prints full error stack on error instead of simple error message.

output

  • Type: string
  • Default: ''
  • Description: Output file name (used by CLI only).

Command Line Interface

The uglifycss command provides access to all functionality via command line:

uglifycss [options] file1.css [file2.css [...]] > output

The CLI can also process CSS from stdin when no files are specified. Note that stdin input is not compatible with the --convert-urls option.

CLI Options

  • --max-line-len n - Add newline every n characters
  • --expand-vars - Expand variables
  • --ugly-comments - Remove newlines within preserved comments
  • --cute-comments - Preserve newlines within and around comments
  • --convert-urls d - Convert relative URLs using directory d as target
  • --debug - Print full error stack on error
  • --output f - Put result in file f
  • --help - Show help message
  • --version - Display version number

CLI Examples

# Basic minification
uglifycss styles.css > minified.css

# Multiple files with options
uglifycss --max-line-len 80 --expand-vars style1.css style2.css > combined.css

# Convert relative URLs and output to file
uglifycss --convert-urls ./build --output dist/styles.css src/styles.css

# Process from stdin (not compatible with --convert-urls)
cat styles.css | uglifycss > minified.css
echo "body{margin:0}" | uglifycss

Advanced Usage

Variable Expansion

const css = `
@variables {
    primary-color: #3498db;
    margin-size: 10px;
}

.header {
    color: var(primary-color);
    margin: var(margin-size);
}
`;

const minified = uglifycss.processString(css, { expandVars: true });
// Variables are expanded and @variables block is removed

URL Conversion

const options = {
    convertUrls: '/build',
    source: ['/src/css'],  // Set internally by processFiles
    target: ['/build']     // Set internally based on convertUrls
};

// Relative URLs in CSS files will be converted based on the target directory
const minified = uglifycss.processFiles(['src/css/styles.css'], options);

Comment Handling

const css = `
/* Regular comment - will be removed */
/*! Important comment - will be preserved */
body {
    margin: 0;
}
`;

// Default behavior - preserves important comments
const minified1 = uglifycss.processString(css);

// Remove newlines in preserved comments
const minified2 = uglifycss.processString(css, { uglyComments: true });

// Preserve newlines in preserved comments
const minified3 = uglifycss.processString(css, { cuteComments: true });

Line Length Control

const css = 'body{margin:0;padding:0;background:#fff;color:#000;font-size:16px;line-height:1.5;}';

// Add newlines every 50 characters
const formatted = uglifycss.processString(css, { maxLineLen: 50 });

Error Handling

UglifyCSS will exit with status code 1 if it encounters file processing errors. Use the debug option for detailed error information:

try {
    const result = uglifycss.processFiles(['nonexistent.css'], { debug: true });
} catch (error) {
    // Error details will be logged to console
    // Process will exit with code 1
}

CSS Optimizations Applied

UglifyCSS applies numerous optimizations including:

  • Removing unnecessary whitespace and comments
  • Compressing hex colors (#AABBCC → #ABC)
  • Converting rgb() to hex when shorter
  • Removing unnecessary units (0px → 0)
  • Shortening color keywords (#ff0000 → red)
  • Optimizing border and background declarations
  • Preserving IE hacks and browser-specific syntax
  • Handling data URLs and preserving Base64 content
  • Normalizing @charset and @import declarations