Getting Started

Installing

Ember App Kit's primary build tool is Grunt, a build tool written in Node.js. If you don't already have Node installed, you can get it from nodejs.org or your package manager of choice (including Homebrew on OSX).

Once you've installed Node, you'll need to install the Grunt command-line tool globally with npm install -g grunt-cli. After that, clone the repo or download it as a zip to get started with the template.

In the folder for your new project, run npm install to install the dependencies Grunt relies on to build. Once your dependencies are installed, you should be able to simply run grunt server and navigate to http://0.0.0.0:8000 to see your new app in action.

Developing

grunt server is the main task used for development. It runs a static Connect server for both your application and its tests, and will automatically rebuild your files in the background as you update them. For a full list of the build tasks that this runs, see your Gruntfile.js.

ES6 Modules & the resolver

Rather than use AMD (Require.js) or CommonJS (Browserify) modules, apps built using the Ember App Kit use ES6 modules, which are built through the ES6 module transpiler. This means that you can build your apps using syntax that will be used in future JavaScript versions, but output AMD modules that can be used by existing JS libraries.

If you've built Ember.js apps before, you're probably used to stuffing everything into a global namespace, following naming conventions so the app can automatically resolve its dependencies (for example, App.FooRoute would know to render App.FooView by default). Using the custom resolver, Ember App Kit apps have similar abilities, but using ES6 modules instead of a global namespace.

For example, this route definition in app/routes/index.js:

var IndexRoute = Ember.Route.extend({
  model: function() {
    return ['red', 'yellow', 'blue'];
  }
});

export default IndexRoute;

Will be built to a module called routes/index. Using the resolver, when Ember looks up the index route, it will find this module and use the IndexRoute object that it exports.

Of course, while automatic resolving is awesome, you can always manually require dependencies with the following syntax:

import MyModel from "models/foo-model";

Which will load the default export (aliased as MyModel) from app/models/foo-model.js.

Testing

The default tests in Ember App Kit use the QUnit library for testing. The included tests demonstrate how to write both unit tests and acceptance/integration tests using the new ember-testing package.

To run the tests in your browser using the QUnit interface, run grunt server and navigate to http://0.0.0.0:8000/tests. Note that just like your app, your tests will auto rebuild when grunt server is running.

Using Karma

The app kit comes with a premade configuration file for running tests in Karma. Karma is a test runner developed by Google for easier cross-browser testing. By default, your app has three tasks for testing:

• grunt test runs your application's tests once using Google Chrome. It outputs code coverage information to the terminal and in tmp/public/coverage.
• grunt test:ci runs your tests in PhantomJS, and is intended primarily for running on a CI server (such as Travis CI).
• grunt test:server is similar to grunt server in that it will automatically watch and rebuild your application on changes. It will also rerun your tests automatically when your code is updated. Unlike running the tests directly through the QUnit page, however, test results are output in the terminal and not the browser.

To modify these tests (including the browser used), edit tasks/options/karma.js.

Travis CI

The app kit comes with a premade .travis.yml to run your tests on Travis CI. Travis CI will run the test script specified in your package.json file. By default, this is is set to grunt build:debug test:ci.

Deploying

grunt build:dist builds a minified, production-ready version of your application to tmp/public. After building, you can preview this version with grunt server:dist.

By default, build:dist will minify and uniquely stamp app.css, vendor.css, your JS vendor dependencies, and your built app.js and templates.js. This task uses grunt-usemin and grunt-rev. See their documentation, as well as their task configurations and public/index.html, for more information on customizing their behavior.

If you use Amazon S3 for hosting your assets, you may want to look into grunt-s3 for deploying your built application.

Extras

These are optional features your app can use.

LESS, Sass, or Stylus

You can use LESS, Sass (scss only), or Stylus by uncommenting the corresponding line in Gruntfile.js and installing the appropriate Grunt plugin: (grunt-contrib-less, grunt-sass, or grunt-contrib-stylus). By default, their tasks are configured to simply compile all of the *.less*, *.scss, or *.styl files in app/styles to app.css in your output.

CoffeeScript

The ES6 module transpiler has full support for CoffeeScript, and Ember App Kit does too. Simply uncomment the coffee entry in Gruntfile.js and install grunt-contrib-coffee. CoffeeScript can be used in both your app's source and in tests.

Ember Data

While the App Kit doesn't come with Ember Data, it can easily be added by downloading it to your vendor/ folder and adding a script tag for it in public/index.html. You can also install Ember Data via Bower (see below).

Bower

Your app can optionally use Bower for managing your client-side dependencies (jQuery, Handlebars, and Ember). The directory is preconfigured to use Bower out of the box, but make sure you remove the pre-existing dependencies in your vendor/ directory from source control.