Ember CLI Clean CSS Addon

3.0.0 · active · verified Tue Apr 21

ember-cli-clean-css is an Ember CLI addon designed to integrate the `clean-css` library into an Ember.js application's build pipeline. It automatically minifies CSS files during development and production builds, aiming to optimize their size for improved loading performance. The current stable version, 3.0.0, primarily features an upgrade to `clean-css` version 5, bringing the latest minification capabilities and features. Its release cadence is generally aligned with updates to `ember-cli` and `clean-css`. This addon differentiates itself by offering a straightforward, low-configuration approach to CSS minification within the Ember ecosystem, directly hooking into the asset build process without requiring manual `clean-css` invocation or complex configuration, making it an essential tool for optimizing Ember application stylesheets.

Common errors

```
Build Error: 'ember-cli-clean-css' options not recognized or causing issues
```
cause Invalid or incompatible options provided in `ember-cli-build.js` for the specific `clean-css` version bundled with the addon.

fix Check the `clean-css` documentation (version 5 for addon v3.x, version 3 for addon v2.x) for valid options and adjust your `ember-cli-build.js` configuration accordingly.
```
Relative CSS asset paths are broken in the deployed application.
```
cause This is a known bug in `ember-cli-clean-css` versions prior to 2.0.1, affecting how relative URLs are handled during minification.

fix Upgrade `ember-cli-clean-css` to version `2.0.1` or higher (`npm install ember-cli-clean-css@latest` or `ember install ember-cli-clean-css`).
```
Error: The 'engines.node' requirement (e.g., '16.* || >= 18') was not met.
```
cause The Node.js version being used is not compatible with the `engines.node` specification in the package's `package.json`.

fix Update your Node.js environment to a compatible version (e.g., Node 16 or 18+). Use `nvm` or `volta` to manage Node.js versions effectively.

Warnings

breaking Version 3.0.0 updated the underlying `clean-css` dependency to version 5. This may introduce changes in minification output or break existing configurations that relied on `clean-css` v4-specific options or behaviors.
Fix: Review your `ember-cli-clean-css` configuration options against the `clean-css` v5 documentation to ensure compatibility and desired output.
breaking Version 2.0.0 explicitly downgraded `clean-css` to version 3 to align with `ember-cli`'s default build setup at the time. If upgrading from an older version that might have used a newer `clean-css`, this would have resulted in a functional downgrade of minification capabilities.
Fix: If advanced `clean-css` features (post v3) are required, upgrade to `ember-cli-clean-css` v3.0.0 or newer to utilize `clean-css` v5.
gotcha Prior to version 2.0.1, a bug caused relative URLs in CSS files to be incorrectly processed post-minification, leading to broken asset paths in built applications.
Fix: Upgrade to `ember-cli-clean-css@^2.0.1` or the latest version to resolve issues with relative URLs.

Install

npm install ember-cli-clean-css npm
yarn add ember-cli-clean-css yarn
pnpm add ember-cli-clean-css pnpm

Imports

Addon Installation
```
ember install ember-cli-clean-css
```
The addon is integrated into your Ember project via the Ember CLI installation command, which adds it to `package.json` and configures it for the build pipeline.
Configuration Options
wrong:
```
import { CleanCSSOptions } from 'ember-cli-clean-css';
```
correct:
```
const app = new EmberApp(defaults, {
  'ember-cli-clean-css': {
    // clean-css options go here
    level: 2, // Example: enables advanced optimizations
    sourceMap: false
  }
});
```
Configuration for the addon, including all `clean-css` options, is passed via the `app.options` object in `ember-cli-build.js`, not via direct JavaScript imports. Consult `clean-css` documentation for available options.
Conditional Disabling
```
const app = new EmberApp(defaults, {
  'ember-cli-clean-css': {
    enabled: process.env.EMBER_ENV !== 'test'
  }
});
```
The addon can be enabled or disabled conditionally using the `enabled` property within its configuration object in `ember-cli-build.js`.

Quickstart

This quickstart demonstrates how to install the addon and provide basic configuration for `clean-css` options within your `ember-cli-build.js` file, including conditional source map generation.

ember install ember-cli-clean-css

// Then, in your ember-cli-build.js file, configure options:
const EmberApp = require('ember-cli/lib/broccoli/ember-app');

module.exports = function(defaults) {
  let app = new EmberApp(defaults, {
    'ember-cli-clean-css': {
      enabled: true, // Set to false to disable minification
      level: {
        1: { 
          all: true, // Set all level 1 optimizations to true
          specialComments: 'none' // Remove all special comments (e.g., @licence)
        },
        2: {
          all: true // Set all level 2 optimizations to true
        }
      },
      // Other clean-css options can be added here
      sourceMap: app.isProduction() // Generate source maps only in production
    }
  });

  return app.toTree();
};

view raw JSON →