Skip to content

Getting Started

Jump to bottom Edit New page
Jan Votava edited this page Feb 7, 2014 · 33 revisions

Installing

Step 1 Install Node Package Manager (NPM)

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).

Step 2 Install Grunt

npm install -g grunt-cli

This will install the Grunt command-line tool globally on your system. If you experience permission issues installing grunt see the Troubleshooting guide for more info.

You can confirm grunt-cli is installed by typing

which grunt-cli

This should print out the path where grunt is installed on your system.

Step 3 Clone or Download Ember App Kit

git clone git@github.com:stefanpenner/ember-app-kit.git

Or you can download it as a zip to get started with the template.

Step 4 Navigate to Ember App Kit project directory

cd ember-app-kit

Step 5 Install local dependencies with node package manager (npm)

npm install

This will install the dependencies Grunt relies on to build your project from source. This will create a node_modules folder in your project and install the source for numerous NPM packages.

Step 6 Launch web server with grunt

grunt server

point your web browser to

http://0.0.0.0:8000

Congratulations. Have fun using Ember App Kit.

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.

Many apps use HTML5 pushState for their URLs. So you can reload the page after navigating to a URL, app-kit will serve the index.html file to any url that does not match an asset. If you follow a link to "/my_crazy_route" then reload the page, your app will still be loaded. You may wish to serve an alternative html file for the catch-all or disable this behavior: See tasks/options/connect.js for this.

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.

Resolving from template helpers

Ember.js has several template helpers that are used to easily resolve and render views and their contexts within a template. The resolver works with these helpers, too:

  • {{partial "foo"}} will render the template within templates/foo.hbs
  • {{view "foo"}} will render the view within views/foo.js.
  • {{render "foo" "bar"}} will render the view within views/foo.js using the controller within controllers/bar.js

Resolving Handlebars helpers

Handlebars helpers will only be found automatically by the resolver if their name contains a dash (reverse-word, translate-text, etc.) This is the result of a choice that was made in Ember, to help both disambiguate properties from helpers, and to mitigate the performance hit of helper resolution for all bindings. The other option is to load it explicitly like so:

In app/helpers/example.js:

var helperFunction = function(value, options) {
  return value.toUpperCase();
};

In app.js:

import exampleHelper from 'appkit/helpers/example';
Ember.Handlebars.registerBoundHelper('example', exampleHelper);

Testing

The default tests in Ember App Kit use the QUnit library. 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 dist/. 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

To enable CoffeeScript in Ember App Kit, you must first add grunt-contrib-coffee to your NPM modules:

npm install --save-dev grunt-contrib-coffee

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:

# app/models/post.coffee
`import User from 'appkit/models/user'`

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

`export default Post`

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

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.

Add a custom footer

Justa

Clone this wiki locally