Sass integration for Ember CLI

11.0.1 · active · verified Wed Apr 22

Ember CLI Sass is an addon for Ember CLI applications that integrates Sass preprocessing into the build pipeline. It provides robust support for generating source maps, configuring include paths, and handling multiple CSS output files via Ember CLI's `outputPaths` configuration. Currently stable at version 11.0.1, the package is actively maintained with recent releases addressing internal chore items and node version compatibility. It defaults to using Dart Sass (compiled to pure JavaScript) for compilation but offers explicit configuration to utilize alternative implementations like `node-sass` (which uses LibSass for potentially faster compilation), allowing developers to choose based on their project's performance and dependency needs. It is a fundamental tool for styling Ember.js projects with Sass, ensuring seamless integration with the Ember CLI build system.

Common errors

```
Error: Cannot find module 'sass'
```
cause The default Dart Sass implementation (or 'sass' package) is missing from your project's `node_modules`.

fix Install the `sass` package: `npm install --save-dev sass`.
```
Node Sass does not yet support your current environment: OS X 64-bit with Node.js X.Y.Z
```
cause `node-sass` has specific binary requirements and might not be compatible with your Node.js version or operating system if pre-compiled binaries are not available or fail to build.

fix Try running `npm rebuild node-sass` to recompile the binding for your environment. If issues persist, check the `node-sass` GitHub repository for compatible Node.js versions or consider switching to the default `sass` (Dart Sass) implementation.
```
Sass compilation failed: file-name.scss
Error: expected '}'
```
cause Indicates a syntax error in your Sass/SCSS file, such as an unclosed curly brace, missing semicolon, or incorrect nesting.

fix Review the specified Sass file and line number for syntax errors. Common issues include unmatched braces, parentheses, or incorrect use of Sass features.

Warnings

breaking Version 11.0.0 dropped support for Node.js versions older than 10. Users on older Node.js runtimes must upgrade their Node.js environment or remain on an older `ember-cli-sass` version.
Fix: Upgrade your Node.js version to 10 or higher. For example, using nvm: `nvm install 16 && nvm use 16`.
gotcha By default, `ember-cli-sass` uses Dart Sass (a pure JavaScript implementation), which can be significantly slower than LibSass (via `node-sass`) for compilation. This might impact build times in larger projects.
Fix: To use `node-sass` (LibSass), install it (`npm install --save-dev node-sass`) and configure `sassOptions.implementation` in `ember-cli-build.js`: `implementation: require('node-sass')`.
gotcha When developing an Ember addon and wanting to distribute compiled CSS, `ember-cli-sass` and the chosen Sass implementation (e.g., `sass`) must be installed as `dependencies` (not `devDependencies`) in the addon's `package.json` to ensure compilation into `dist/assets/vendor.css`.
Fix: For addon development, use `npm install --save ember-cli-sass sass` (or `node-sass`) instead of `--save-dev`.

Install

npm install ember-cli-sass npm
yarn add ember-cli-sass yarn
pnpm add ember-cli-sass pnpm

Imports

EmberApp config
```
let app = new EmberApp(defaults, { sassOptions: { /* ... */ } });
```
Configuration for ember-cli-sass is done by passing a `sassOptions` object to the `EmberApp` constructor in `ember-cli-build.js`.
nodeSass (implementation)
wrong:
```
import nodeSass from 'node-sass';
```
correct:
```
const nodeSass = require('node-sass');
```
Used in `ember-cli-build.js` to explicitly set `node-sass` as the implementation for `sassOptions`.
sass (implementation)
wrong:
```
import sass from 'sass';
```
correct:
```
const sass = require('sass');
```
While `ember-cli-sass` uses `sass` (Dart Sass) by default, you can explicitly pass it as the implementation in `ember-cli-build.js` similar to `node-sass`.

Quickstart

Demonstrates `ember-cli-sass` installation and basic configuration within `ember-cli-build.js`, including `sassOptions` for include paths and an example of multiple CSS output paths.

/* ember-cli-build.js */
const EmberApp = require('ember-cli/lib/broccoli/ember-app');
const defaults = require('lodash.defaultsdeep');

// Optional: If you want to use node-sass for potentially faster compilation
// const nodeSass = require('node-sass');

module.exports = function(env) {
  let app = new EmberApp(defaults(env.APP, {
    // Configure ember-cli-sass options here
    sassOptions: {
      // implementation: nodeSass, // Uncomment to use node-sass
      includePaths: [
        'app/styles',
        'node_modules/my-ui-library/scss'
      ],
      sourceMap: true, // Defaults to true in development
      extension: 'scss' // Defaults to 'scss'
    },

    // Example for processing multiple SASS files
    outputPaths: {
      app: {
        css: {
          app: '/assets/application-name.css',
          'themes/alpha': '/assets/themes/alpha.css' // Compile app/styles/themes/alpha.scss
        }
      }
    }
  }));

  return app.toTree();
};

/* app/styles/app.scss */
@import 'variables';
body {
  font-family: sans-serif;
  color: $primary-color;
}

/* app/styles/_variables.scss */
$primary-color: #336699;

view raw JSON →