Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
516 lines (398 sloc) 16.7 KB
layout title permalink category github
post
Asset Compilation
asset-compilation
user-guide

Raw Assets

  • public/assets vs app/styles

To add images, fonts, or other assets, place them in the public/assets directory. For example, if you place logo.png in public/assets/images, you can reference it in templates with assets/images/logo.png or in stylesheets with url('/assets/images/logo.png').

This functionality of Ember-CLI comes from broccoli-asset-rev. Be sure to check out all the options and usage notes.

JS Transpiling

Ember-cli automatically transpiles future javascript (ES6/ES2015, ES2016 and beyond) into standard ES5 javascript that runs on every browser using Babel JS with the ember-cli-babel addon.

The default configuration handles most project's needs, but you can provide options to the transpile to disable specific transformations if by example your app only targets ES6 capable browsers, or on the contrary enable transpilation of some experimental features that not enabled by default just yet.

You can configure how babel works using the babel option in ember-cli-build.js. By example for disabling ES6/2015 features you'd do:

{% highlight js %} // ember-cli-build.js var EmberApp = require('ember-cli/lib/broccoli/ember-app');

module.exports = function(defaults) { var app = new EmberApp(defaults, { babel: { blacklist: [ 'es6.arrowFunctions', 'es6.blockScoping', 'es6.classes', 'es6.destructuring', 'es6.parameters', 'es6.properties.computed', // ...more options ] } });

//... return app.toTree(); }; {% endhighlight %}

This options are just forwarded to Babel. Ember-cli uses Babel 5.X at the moment and you can check its documentation for a comprehensive list of all available transformations and options.

Work is being done for upgrading to Babel 6. You can track the progress and help.

Minifying

The compiled css-files are minified by broccoli-clean-css or broccoli-csso, if it is installed locally. You can pass minifer-specific options to them using the minifyCSS:options object in your ember-cli-build. Minification is enabled by default in the production-env and can be disabled using the minifyCSS:enabled switch.

Similarly, the js-files are minified with broccoli-uglify-js in the production-env by default. You can pass custom options to the minifier via the minifyJS:options object in your ember-cli-build. To enable or disable JS minification you may supply a boolean value for minifyJS:enabled.

For example, to disable minifying of CSS and JS, add in ember-cli-build.js: {% highlight js %} // ember-cli-build.js var EmberApp = require('ember-cli/lib/broccoli/ember-app');

module.exports = function(defaults) { var app = new EmberApp(defaults, { minifyJS: { enabled: false }, minifyCSS: { enabled: false } });

//... return app.toTree(); }; {% endhighlight %}

Exclude from minification

To exclude assets from dist/assets from being minificated, one can pass options for broccoli-uglify-sourcemap like so:

{% highlight js %} // ember-cli-build.js var EmberApp = require('ember-cli/lib/broccoli/ember-app');

module.exports = function(defaults) { var app = new EmberApp(defaults, { minifyJS: { options: { exclude: ["**/vendor.js"] } } });

//... return app.toTree(); }; {% endhighlight %}

This would exclude the resulting vendor.js file from being minificated.

Source Maps

Ember CLI supports producing source maps for your concatenated and minified JS source files.

Source maps are configured by the EmberApp sourcemaps option, and are disabled in production by default. Pass sourcemaps: {enabled: true} to your EmberApp constructor to enable source maps for javascript. Use the extensions option to add other formats, such as coffeescript and CSS: {extensions: ['js', 'css', 'coffee']}. JS is supported out-of-the-box. CSS is not currently supported. For other source formats (Sass, Coffee, etc) refer to their addons.

Default ember-cli-build.js:

{% highlight bash %} import EmberApp from 'ember-cli/lib/broccoli/ember-app'; var app = new EmberApp({ sourcemaps: { enabled: EmberApp.env() !== 'production', extensions: ['js'] } }); {% endhighlight %}

Stylesheets

Ember CLI supports plain CSS out of the box. You can add your css styles to app/styles/app.css and it will be served at assets/application-name.css.

For example, to add bootstrap in your project you need to do the following: {% highlight bash %} bower install bootstrap --save {% endhighlight %}

In ember-cli-build.js add the following: {% highlight bash %} app.import('bower_components/bootstrap/dist/css/bootstrap.css'); {% endhighlight %} it's going to tell Broccoli that we want this file to be concatenated with our vendor.css file.

To use a CSS preprocessor, you'll need to install the appropriate Broccoli plugin. When using a preprocessor, Broccoli is configured to look for an app.less, app.scss, app.sass, or app.styl manifest file in app/styles. This manifest should import any additional stylesheets.

All your preprocessed stylesheets will be compiled into one file and served at assets/application-name.css.

If you would like to change this behavior, or compile to multiple output stylesheets, you can adjust the Output Paths Configuration

CSS

To use plain CSS with app.css:

  • Write your styles in app.css and/or organize your CSS into multiple stylesheet files and import these files with @import from within app.css.
  • CSS @import statements (e.g. @import 'typography.css';) must be valid CSS, meaning @import statements must precede all other rules and so be placed at the top of app.css.
  • In the production build, the @import statements are replaced with the contents of their files and the final minified, concatenated single CSS file is built to dist/assets/yourappname-FINGERPRINT_GOES_HERE.css.
  • Any individual CSS files are also built and minified into dist/assets/ in case you need them as standalone stylesheets.
  • Relative pathing gets changed (how to customize?)

Example app.css with valid @import usage:

{% highlight css %} /* @imports must appear at top of stylesheet to be valid CSS */ @import 'typography.css'; @import 'forms.css';

/* Any CSS rules must go after any @imports */ .first-css-rule { color: red; } ... {% endhighlight %}

CSS Preprocessors

To use one of the following preprocessors, all you need to do is install the appropriate NPM module. The respective files will be picked up and processed automatically.

LESS

To enable LESS, you'll need to add ember-cli-less to your NPM modules.

{% highlight bash %} ember install ember-cli-less {% endhighlight %}

SCSS/SASS

To enable SCSS/SASS, you'll need to install the ember-cli-sass addon to your project (defaults to .scss, .sass allowed via configuration).

{% highlight bash %} ember install ember-cli-sass {% endhighlight %}

You can configure your project to use .sass in your ember-cli-build.js:

{% highlight javascript %} // ember-cli-build.js var app = new EmberApp(defaults, { sassOptions: { extension: 'sass' } }); {% endhighlight %}

Compass

To use Compass with your ember-cli app, install ember-cli-compass-compiler addon using NPM.

{% highlight bash %} ember install ember-cli-compass-compiler {% endhighlight %}

Stylus

To enable Stylus, you must first add ember-cli-stylus to your NPM modules:

{% highlight bash %} ember install ember-cli-stylus {% endhighlight %}

CoffeeScript

To enable CoffeeScript, you must first add ember-cli-coffeescript to your NPM modules:

{% highlight bash %} ember install ember-cli-coffeescript {% endhighlight %}

The modified package.json should be checked into source control. CoffeeScript can be used in your app's source and in tests, just use the .coffee extension on any file.

The ES6 module transpiler does not directly support CoffeeScript, but using them together is simple. Use the ` character to escape out to JavaScript from your .coffee files, and use the ES6 syntax there:

{% highlight coffeescript %}

app/models/post.coffee

import Ember from 'ember' import User from 'appkit/models/user'

Post = Ember.Object.extend init: (userId) -> @set 'user', User.findById(userId)

export default Post {% endhighlight %}

Note that earlier versions of the transpiler had explicit support for CoffeeScript, but that support has been removed.

EmberScript

To enable EmberScript, you must first add broccoli-ember-script to your NPM modules:

{% highlight bash %} npm install broccoli-ember-script --save-dev {% endhighlight %}

Note that the ES6 module transpiler is not directly supported with Emberscript, to allow use of ES6 modules use the ` character to escape raw Javascript similar to the CoffeeScript example above.

Emblem

For Emblem, run the following commands:

{% highlight bash %} ember install ember-cli-emblem {% endhighlight %}

If you're using the older broccoli-emblem-compiler addon, you need to switch to ember-cli-emblem. The older broccoli-emblem-compiler compiles directly to JS instead of Handlebars and therefore is broken on all newer version of HTMLBars.

Fingerprinting and CDN URLs

Fingerprinting is done using the addon broccoli-asset-rev (which is included by default).

When the environment is production (e.g. ember build --environment=production), the addon will automatically fingerprint your js, css, png, jpg, and gif assets by appending an md5 checksum to the end of their filename (e.g. assets/yourapp-9c2cbd818d09a4a742406c6cb8219b3b.js). In addition, your html, js, and css files will be re-written to include the new name. There are a few options you can pass in to EmberApp in your ember-cli-build.js to customize this behavior.

  • enabled - Default: app.env === 'production' - Boolean. Enables fingerprinting if true. True by default if current environment is production.
  • exclude - Default: [] - An array of strings. If a filename contains any item in the exclude array, it will not be fingerprinted.
  • ignore - Default: [] - An array of strings. If a filename contains any item in the ignore array, the contents of the file will not be processed for fingerprinting.
  • extensions - Default: ['js', 'css', 'png', 'jpg', 'gif', 'map'] - The file types to add md5 checksums.
  • prepend - Default: '' - A string to prepend to all of the assets. Useful for CDN urls like https://subdomain.cloudfront.net/
  • replaceExtensions - Default: ['html', 'css', 'js'] - The file types to replace source code with new checksum file names.
  • customHash - When specified, this is appended to fingerprinted filenames instead of the md5. Pass null to suppress the hash, which can be useful when using prepend.

As an example, this ember-cli-build will exclude any file in the fonts/169929 directory as well as add a cloudfront domain to each fingerprinted asset.

{% highlight javascript %} // ember-cli-build.js var app = new EmberApp({ fingerprint: { exclude: ['fonts/169929'], prepend: 'https://subdomain.cloudfront.net/' } }); {% endhighlight %}

The end result will turn

{% highlight html %}