CSSO4J - Java Wrapper for CSSO CSS Optimizer

A Java wrapper around the CSSO (CSS Optimizer) library using GraalVM JavaScript engine. This library allows you to minify CSS directly from Java applications without requiring a separate Node.js runtime.

Features

• Full CSSO Integration: Access to all CSSO minification features
• Thread-Safe: Safe for concurrent use in multi-threaded applications
• Java Records: Modern Java API using Records for configuration and results
• Source Maps: Optional source map generation
• Block Minification: Support for CSS declaration blocks (e.g., from style attributes)
• Zero Node.js Dependency: Runs entirely within the JVM using GraalVM

Requirements

• Java 17 or higher (for Records support)
• GraalVM JavaScript engine (automatically included as dependency)

Installation

Add the dependency to your pom.xml:

<dependency>
    <groupId>org.mycore.web</groupId>
    <artifactId>csso4j</artifactId>
    <version>1.0.0</version>
</dependency>

Quick Start

Basic CSS Minification

import org.mycore.web.csso4j.CssMinifier;
import org.mycore.web.csso4j.MinifyResult;

String css = """
    .header {
        background-color: #ffffff;
        padding: 20px;
        margin: 10px 15px 20px 25px;
    }
    """;

MinifyResult result = CssMinifier.minify(css);
System.out.println(result.css());
// Output: .header{background-color:#fff;padding:20px;margin:10px 15px 20px 25px}

Minification with Custom Options

import org.mycore.web.csso4j.MinifyOptions;

MinifyOptions options = new MinifyOptions(
    true,           // restructure - enable structural optimizations
    true,           // sourceMap - generate source map
    "styles.css",   // filename - for source map
    false,          // debug - disable debug mode
    false,          // forceMediaMerge - don't force media rule merging
    MinifyOptions.CommentHandling.EXCLAMATION,  // comments - keep /*! */ comments
    false,          // cloneAst - don't clone AST
    null            // usageData - no usage data
);

MinifyResult result = CssMinifier.minify(css, options);

System.out.println("Minified CSS: " + result.css());
if (result.hasSourceMap()) {
    System.out.println("Source Map: " + result.sourceMap());
}

Factory Methods for Common Configurations

// Default CSSO settings
MinifyOptions defaults = MinifyOptions.defaults();

// Minimal optimization (faster, larger output)
MinifyOptions minimal = MinifyOptions.minimal();

// With source map enabled
MinifyOptions withSourceMap = MinifyOptions.withSourceMap("input.css");

CSS Declaration Block Minification

For minifying CSS declarations (e.g., from HTML style attributes):

String declarations = "color: #ff0000; font-weight: bold; margin: 10px;";
MinifyResult result = CssMinifier.minifyBlock(declarations);
System.out.println(result.css());
// Output: color:red;font-weight:bold;margin:10px

Configuration Options

The MinifyOptions record provides access to all CSSO configuration parameters:

Option	Type	Default	Description
restructure	boolean	true	Enable structural optimizations (merging selectors, reordering)
sourceMap	boolean	false	Generate source map
filename	String	"<unknown>"	Input filename (used in source maps)
debug	boolean	false	Enable CSSO debug mode
forceMediaMerge	boolean	false	Aggressively merge @media rules
comments	MinifyOptions.CommentHandling	EXCLAMATION	Comment handling: EXCLAMATION, FIRST_EXCLAMATION, or FALSE
cloneAst	boolean	false	Clone AST before processing
usageData	Object	null	Usage data for more aggressive optimizations

API Reference

CssMinifier

Main facade class providing static methods for CSS minification:

• minify(String css) - Minify CSS with default options
• minify(String css, MinifyOptions options) - Minify CSS with custom options
• minifyBlock(String declarations) - Minify CSS declarations with default options
• minifyBlock(String declarations, MinifyOptions options) - Minify CSS declarations with custom options
• close() - Close the JavaScript context (optional cleanup)

MinifyResult

Result record containing:

• css() - The minified CSS string
• sourceMap() - Source map as JSON string (null if not requested)
• hasSourceMap() - Check if source map is present

Exception Handling

try {
    MinifyResult result = CssMinifier.minify(invalidCss);
} catch (CssMinificationException e) {
    System.err.println("Minification failed: " + e.getMessage());
}

Performance Considerations

• First Call Overhead: The first minification call initializes the GraalVM JavaScript context, which may take some time
• Subsequent Calls: Very fast, as the JavaScript context is reused

Comparison with CSSO CLI

This library provides the same functionality as the CSSO command-line tool:

CLI Option	Java Equivalent
--restructure-off	restructure: false
--source-map	sourceMap: true
--input <file>	filename: "<file>"
--comments exclamation	comments: EXCLAMATION
--force-media-merge	forceMediaMerge: true
--debug	debug: true

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.