minifier-css

The minifier-css package provides CSS parsing, minification, and transformation capabilities for Meteor applications using PostCSS and cssnano. It handles URL rewriting, source maps, and CSS merging.

Overview

This package exports CssTools, a comprehensive toolkit for CSS processing. It uses modern PostCSS infrastructure for parsing and cssnano for minification, making it compatible with current CSS standards.

Dependencies

{
  "postcss": "8.5.1",
  "cssnano": "5.1.15"
}

Installation

Included by default in Meteor’s build system. For manual use:

api.use('minifier-css', 'server');

API

CssTools.parseCss(cssText, options)

Parse CSS string into a PostCSS AST (Abstract Syntax Tree). Parameters:

cssText (string): CSS content to parse
options (Object): PostCSS parser options
- from (string): File path for source maps (formerly source)

Returns: PostCSS Root AST Example:

import { CssTools } from 'meteor/minifier-css';

const css = '.button { color: red; }';
const ast = CssTools.parseCss(css, { from: 'button.css' });

CssTools.stringifyCss(cssAst, options)

Convert PostCSS AST back to CSS string with optional source maps. Parameters:

cssAst (Object): PostCSS Root AST
options (Object): PostCSS stringify options
- map (Object): Source map configuration (formerly sourcemap)
- from (string): Source file path

Returns: Object with:

code (string): Generated CSS string
map (Object|null): Source map if enabled

Example:

const ast = CssTools.parseCss('.button { color: red; }');
const result = CssTools.stringifyCss(ast, {
  map: {
    inline: false,
    annotation: false,
    sourcesContent: false
  }
});

console.log(result.code); // CSS string
console.log(result.map);  // Source map JSON

CssTools.minifyCss(cssText)

Minify CSS using cssnano in safe mode. Parameters:

cssText (string): CSS to minify

Returns: Promise<string[]> - Array containing minified CSS Example:

const css = `
  .button {
    color: red;
    background: blue;
  }
`;

const minified = await CssTools.minifyCss(css);
console.log(minified[0]);
// Output: ".button{color:red;background:blue}"

CssTools.minifyCssAsync(cssText)

Alias for minifyCss(). Both methods are asynchronous. Example:

const result = await CssTools.minifyCssAsync(cssText);

CssTools.mergeCssAsts(cssAsts, warnCb)

Merge multiple CSS ASTs into a single AST, handling imports and charset rules. Parameters:

cssAsts (Array): Array of PostCSS Root objects
warnCb (Function): Callback for warnings (filename, message) => {}

Returns: PostCSS Root object Example:

const ast1 = CssTools.parseCss('@import "base.css"; .btn { }');
ast1.filename = 'buttons.css';

const ast2 = CssTools.parseCss('.link { color: blue; }');
ast2.filename = 'links.css';

const merged = CssTools.mergeCssAsts([ast1, ast2], (file, msg) => {
  console.warn(`${file}: ${msg}`);
});

Merge behavior:

@import rules are moved to the beginning
@charset rules are removed (UTF-8 assumed)
Warns about mid-file imports
URL paths are rewritten to absolute

CssTools.rewriteCssUrls(ast)

Rewrite relative URLs in CSS to absolute paths. Parameters:

ast (Object): PostCSS Root AST (modified in place)

Returns: Undefined (modifies AST in place) Example:

const css = '.bg { background: url("../images/bg.png"); }';
const ast = CssTools.parseCss(css);
ast.filename = '/client/styles/main.css';

CssTools.rewriteCssUrls(ast);
const result = CssTools.stringifyCss(ast);
// URLs are now absolute: url("/client/images/bg.png")

Configuration

Minification Options

The package uses cssnano in safe mode:

await postcss([cssnano({ safe: true })])
  .process(cssText, { from: void 0 })

Safe mode prevents:

Unsafe selector merging
Aggressive shorthand optimization
Removal of potentially needed rules

Source Maps

Enable source maps during stringification:

const options = {
  map: {
    inline: false,        // Don't inline source map
    annotation: false,    // Don't add source map comment
    sourcesContent: false // Don't include source content
  }
};

const result = CssTools.stringifyCss(ast, options);

URL Rewriting

How It Works

The package rewrites relative URLs to work correctly when CSS files are merged:

var cssUrlRegex = /url\s*\(\s*(['"]?)(.+?)\1\s*\)/gi;

while (parts = cssUrlRegex.exec(value)) {
  const resource = url.parse(parts[2]);
  
  // Skip absolute URLs, protocols, network paths, and fragments
  if (resource.protocol !== null ||
      resource.href.startsWith('//') ||
      resource.href.startsWith('#')) {
    continue;
  }
  
  // Rewrite relative to absolute
  let absolutePath = isRelative(resource.path)
    ? pathJoin(basePath, resource.path)
    : resource.path;
}

URL Patterns

Not rewritten:

url(http://example.com/img.png) - HTTP/HTTPS
url(//cdn.example.com/img.png) - Network path
url(data:image/png;base64,...) - Data URLs
url(#fragment) - Fragments

Rewritten:

url(../images/bg.png) - Relative paths
url(./icon.png) - Current directory
url(bg.png) - Relative to CSS file

Package Path Handling

Special handling for Meteor packages:

if (! basePath.match(/^\/?packages\//i)) {
  basePath = "/";
}

Files in /packages/* keep their path prefix
Other files are served from root /

Deployment Prefix Support

URLs are made relative to merged CSS for ROOT_URL support:

const relativeToMergedCss = pathRelative(mergedCssPath, absolutePath);
const newCssUrl = `url(${quote}${relativeToMergedCss}${quote})`;

Example:

// Original: url("../images/bg.png")
// After merge: url("images/bg.png")
// With ROOT_URL=http://example.com/app/
// Browser resolves to: http://example.com/app/images/bg.png

Charset Handling

UTF-8 Only

The package assumes all CSS is UTF-8:

const charsetRules = ast.nodes.filter(rulesPredicate('charset'));

if (charsetRules.some((rule) => {
  return ! /^(['"])UTF-8\1$/.test(rule.params);
})) {
  warnCb(
    ast.filename,
    '@charset rules in this file will be ignored as UTF-8 is the ' +
    'only encoding supported'
  );
}

ast.nodes = ast.nodes.filter(rulesPredicate('charset', true));

Valid charset rules:

@charset "UTF-8";
@charset 'UTF-8';

All other charsets: Removed with warning

Import Handling

Import Extraction

Imports are extracted and moved to file beginning:

let importCount = 0;
for (let i = 0; i < ast.nodes.length; i++) {
  if (! rulesPredicate(['import', 'comment'])(ast.nodes[i])) {
    importCount = i;
    break;
  }
}

const imports = ast.nodes.splice(0, importCount);
newAst.nodes.push(...imports);

Mid-File Import Warning

Warns about imports after other rules:

if (ast.nodes.some(rulesPredicate('import'))) {
  warnCb(
    ast.filename,
    'There are some @import rules in the middle of a file. This ' +
    'might be a bug, as imports are only valid at the beginning of ' +
    'a file.'
  );
}

Performance Optimization

Functions are profiled when available:

if (typeof Profile !== 'undefined') {
  [
    'parseCss',
    'stringifyCss',
    'minifyCss',
    'minifyCssAsync',
    'mergeCssAsts',
    'rewriteCssUrls',
  ].forEach(funcName => {
    CssTools[funcName] = Profile(`CssTools.${funcName}`, CssTools[funcName]);
  });
}

Backwards Compatibility

Legacy css-parse/css-stringify

The package maintains compatibility with the old API:

// Legacy: { source: 'filename' }
if (options.source) {
  options.from = options.source;
  delete options.source;
}

// Legacy: { sourcemap: true }
if (options.sourcemap) {
  options.map = {
    inline: false,
    annotation: false,
    sourcesContent: false,
  };
  delete options.sourcemap;
}

Complete Example

import { CssTools } from 'meteor/minifier-css';

// Parse multiple CSS files
const css1 = CssTools.parseCss(`
  @import url("reset.css");
  .button { background: url("../img/btn.png"); }
`);
css1.filename = '/client/styles/buttons.css';

const css2 = CssTools.parseCss(`
  .link { color: blue; }
`);
css2.filename = '/client/styles/links.css';

// Merge ASTs
const merged = CssTools.mergeCssAsts([css1, css2], (file, msg) => {
  console.warn(`Warning in ${file}: ${msg}`);
});

// Stringify with source maps
const { code, map } = CssTools.stringifyCss(merged, {
  map: {
    inline: false,
    annotation: false,
    sourcesContent: false
  }
});

// Minify the result
const [minified] = await CssTools.minifyCss(code);

console.log('Minified CSS:', minified);
console.log('Source map:', map);

Testing

Comprehensive test suite:

Package.onTest(function (api) {
  api.use('ecmascript');
  api.use('tinytest');
  api.addFiles([
    'minifier-tests.js',
    'minifier-async-tests.js',
    'urlrewriting-tests.js'
  ], 'server');
});

Run tests:

meteor test-packages ./packages/minifier-css

Common Issues

Issue: URLs broken after merge

Solution: Ensure ast.filename is set with the source file path before merging:

const ast = CssTools.parseCss(cssText);
ast.filename = '/path/to/source.css';

Issue: Charset warnings

Solution: Remove @charset rules or ensure they specify UTF-8:

/* Good */
@charset "UTF-8";

/* Bad - will be removed */
@charset "ISO-8859-1";

Issue: Mid-file imports

Solution: Move all @import statements to the beginning:

/* Good */
@import url("base.css");
.button { }

/* Bad */
.button { }
@import url("base.css"); /* Warning */

Package System

Core Packages

Build Packages

Overview

Dependencies

Installation

API

CssTools.parseCss(cssText, options)

CssTools.stringifyCss(cssAst, options)

CssTools.minifyCss(cssText)

CssTools.minifyCssAsync(cssText)

CssTools.mergeCssAsts(cssAsts, warnCb)

CssTools.rewriteCssUrls(ast)

Configuration

Minification Options

Source Maps

URL Rewriting

How It Works

URL Patterns

Package Path Handling

Deployment Prefix Support

Charset Handling

UTF-8 Only

Import Handling

Import Extraction

Mid-File Import Warning

Performance Optimization

Backwards Compatibility

Legacy css-parse/css-stringify

Complete Example

Testing

Common Issues

Issue: URLs broken after merge

Issue: Charset warnings

Issue: Mid-file imports

Build docs developers (and LLMs) love

Package System

Core Packages

Build Packages

Documentation Index

​Overview

​Dependencies

​Installation

​API

​CssTools.parseCss(cssText, options)

​CssTools.stringifyCss(cssAst, options)

​CssTools.minifyCss(cssText)

​CssTools.minifyCssAsync(cssText)

​CssTools.mergeCssAsts(cssAsts, warnCb)

​CssTools.rewriteCssUrls(ast)

​Configuration

​Minification Options

​Source Maps

​URL Rewriting

​How It Works

​URL Patterns

​Package Path Handling

​Deployment Prefix Support

​Charset Handling

​UTF-8 Only

​Import Handling

​Import Extraction

​Mid-File Import Warning

​Performance Optimization

​Backwards Compatibility

​Legacy css-parse/css-stringify

​Complete Example

​Testing

​Common Issues

​Issue: URLs broken after merge

​Issue: Charset warnings

​Issue: Mid-file imports

Build docs developers (and LLMs) love

Overview

Dependencies

Installation

API

CssTools.parseCss(cssText, options)

CssTools.stringifyCss(cssAst, options)

CssTools.minifyCss(cssText)

CssTools.minifyCssAsync(cssText)

CssTools.mergeCssAsts(cssAsts, warnCb)

CssTools.rewriteCssUrls(ast)

Configuration

Minification Options

Source Maps

URL Rewriting

How It Works

URL Patterns

Package Path Handling

Deployment Prefix Support

Charset Handling

UTF-8 Only

Import Handling

Import Extraction

Mid-File Import Warning

Performance Optimization

Backwards Compatibility

Legacy css-parse/css-stringify

Complete Example

Testing

Common Issues

Issue: URLs broken after merge

Issue: Charset warnings

Issue: Mid-file imports