ember-cli-sass uses Sass to preprocess your ember-cli app's styles, and provides support for source maps and include paths. It provides support for the common use case for Ember.js projects:
- Source maps by default in development
- Support for
outputPaths
configuration - Provides the ability to specify include paths
- Edit SASS in Chrome Dev Tools
ember install ember-cli-sass
If you want to use ember-cli-sass in an addon and you want to distribute the compiled CSS it must be installed as a dependency
so that addon/styles/addon.scss
is compiled into dist/assets/vendor.css
. This can be done using:
npm install --save ember-cli-sass sass
By default this addon uses a distribution of Dart Sass that is compiled to pure JavaScript. Dart Sass is the reference implementation for Sass, but it does provides significantly slower compilation times than LibSass (via node-sass
).
If you would like to use an alternative implementation (e.g. node-sass
), you must
pass a Sass implementation to the sassOptions
config property in ember-cli-build.js
(or in Brocfile.js
if you are
using an Ember CLI version older than 1.13):
var nodeSass = require('node-sass');
var app = new EmberApp({
sassOptions: {
implementation: nodeSass
}
});
By default this addon will compile app/styles/app.scss
into dist/assets/app.css
and produce
a source map for your delectation.
If you want more control, you can pass additional options to sassOptions
:
includePaths
: an array of include pathsonlyIncluded
: true/false whether to use only what is inapp/styles
andincludePaths
. This may helps with performance, particularly when using NPM linked modulessourceMap
: controls whether to generate sourceMaps, defaults totrue
in development. The sourceMap file will be saved tooptions.outputFile + '.map'
extension
: specifies the file extension for the input files, defaults toscss
. Set tosass
if you want to use.sass
instead.passthrough
: an optional hash of broccoli-funnel configuration for files from the styles tree to be passed through todist
- See broccoli-sass-source-maps for a list of other supported options.
If you need to process multiple files, it can be done by configuring the output paths in your ember-cli-build.js
:
var app = new EmberApp({
outputPaths: {
app: {
css: {
'app': '/assets/application-name.css',
'themes/alpha': '/assets/themes/alpha.css'
}
}
}
});
Source maps work for reading with no configuration, but to edit the SASS in the Dev Tools you need to configure your Workspace:
- Open app.scss in Dev Tools (you can use ⌘P and search for "app.scss")
- Right click in the Sources panel on the right of the Sources tab and select Add Folder to Workspace
- Select the root directory of your project
- Right click on app.scss and select Map to File System Resource...
- Select app.scss from your project directory
The following example assumes your bower packages are installed into bower_components/
.
Install some SASS:
bower install --save foundation
Specify some include paths in your ember-cli-build.js
:
var app = new EmberApp({
sassOptions: {
includePaths: [
'bower_components/foundation/scss'
]
}
});
Import some deps into your app.scss:
@import 'foundation'; /* import everything */
/* or just import the bits you need: @import 'foundation/functions'; */
To compile SASS within an ember-cli addon, there are a few additional steps:
-
Include your styles in
addon/styles/addon.scss
. -
Ensure you've installed
ember-cli-sass
and eithersass
ornode-sass
underdependencies
in yourpackage.json
. -
Define an
included
function in your app:// in your index.js module.exports = { name: 'my-addon', included: function(/* app */) { this._super.included.apply(this, arguments); } };
If you omit this step, it will throw the following error:
Cannot read property 'sassOptions' of undefined TypeError: Cannot read property 'sassOptions' of undefined at Class.module.exports.sassOptions (~/my-plugin/node_modules/ember-cli-sass/index.js:43:48)
-
Make sure your dummy app contains an
app.scss
-
If you run
ember build dist
, your styles fromaddon/styles/addon.scss
should appear correctly indist/assets/vendor.css
As an alternative to the above, some addons may choose to allow their SASS to be used in the parent app, rather than the compiled CSS. This has the advantage of easily allowing users to use and override your SASS. The steps for this setup are as follows:
- Instead of including your styles in
addon/styles/addon.scss
, place them inapp/styles/your-addon-name.scss
. Document that your user can now add@import 'your-addon-name';
to theirapp.scss
file. In the lines before this import they can choose to override any variables your addon marks with default. - Ensure steps 2, 3 and 4 are completed as per the standard addon usage section above.
To re-use SASS definitions from an in-repo-addon within an in-repo-engine, you
need to add the in-repo addons' path to the includePaths
. So basically if you
have a directory layout like this (where common
is an in-repo addon):
app
└── lib
├── my-in-repo-engine
│ ├── addon
│ │ └── styles
│ │ └── addon.scss
│ └── index.js
└── common
└── app
└── styles
└── common
└── vars.scss
The app/lib/my-in-repo-engine/index.js
should look like this:
const EngineAddon = require('ember-engines/lib/engine-addon');
module.exports = EngineAddon.extend({
sassOptions: {
includePaths: ['lib/common/app/styles']
},
...
};
and then you can include the definitions inside the engines SASS files via:
@import "common/vars";
- v9.0.0 Added support for multiple sass implementations (e.g. Dart Sass, LibSass, etc.) The default Sass implementation is Dart Sass, which is now the reference implementation of Sass. This provides significantly slower compilation times than node-sass, but you can see instructions above if you'd like to continue using node-sass.