{"id":15426,"library":"ember-cli-clean-css","title":"Ember CLI Clean CSS Addon","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/ember-cli/ember-cli-clean-css","tags":["javascript","ember-addon"],"install":[{"cmd":"npm install ember-cli-clean-css","lang":"bash","label":"npm"},{"cmd":"yarn add ember-cli-clean-css","lang":"bash","label":"yarn"},{"cmd":"pnpm add ember-cli-clean-css","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core library for CSS minification; version tied to addon's major version (v5 for addon v3.0.0).","package":"clean-css","optional":false},{"reason":"Required for any Ember CLI addon to function within an Ember.js project.","package":"ember-cli","optional":false}],"imports":[{"note":"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.","symbol":"Addon Installation","correct":"ember install ember-cli-clean-css"},{"note":"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.","wrong":"import { CleanCSSOptions } from 'ember-cli-clean-css';","symbol":"Configuration Options","correct":"const app = new EmberApp(defaults, {\n  'ember-cli-clean-css': {\n    // clean-css options go here\n    level: 2, // Example: enables advanced optimizations\n    sourceMap: false\n  }\n});"},{"note":"The addon can be enabled or disabled conditionally using the `enabled` property within its configuration object in `ember-cli-build.js`.","symbol":"Conditional Disabling","correct":"const app = new EmberApp(defaults, {\n  'ember-cli-clean-css': {\n    enabled: process.env.EMBER_ENV !== 'test'\n  }\n});"}],"quickstart":{"code":"ember install ember-cli-clean-css\n\n// Then, in your ember-cli-build.js file, configure options:\nconst EmberApp = require('ember-cli/lib/broccoli/ember-app');\n\nmodule.exports = function(defaults) {\n  let app = new EmberApp(defaults, {\n    'ember-cli-clean-css': {\n      enabled: true, // Set to false to disable minification\n      level: {\n        1: { \n          all: true, // Set all level 1 optimizations to true\n          specialComments: 'none' // Remove all special comments (e.g., @licence)\n        },\n        2: {\n          all: true // Set all level 2 optimizations to true\n        }\n      },\n      // Other clean-css options can be added here\n      sourceMap: app.isProduction() // Generate source maps only in production\n    }\n  });\n\n  return app.toTree();\n};","lang":"javascript","description":"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."},"warnings":[{"fix":"Review your `ember-cli-clean-css` configuration options against the `clean-css` v5 documentation to ensure compatibility and desired output.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"fix":"Upgrade to `ember-cli-clean-css@^2.0.1` or the latest version to resolve issues with relative URLs.","message":"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.","severity":"gotcha","affected_versions":"<2.0.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Invalid or incompatible options provided in `ember-cli-build.js` for the specific `clean-css` version bundled with the addon.","error":"Build Error: 'ember-cli-clean-css' options not recognized or causing issues"},{"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`).","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.","error":"Relative CSS asset paths are broken in the deployed application."},{"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.","cause":"The Node.js version being used is not compatible with the `engines.node` specification in the package's `package.json`.","error":"Error: The 'engines.node' requirement (e.g., '16.* || >= 18') was not met."}],"ecosystem":"npm"}