Skip to content

Getting Started

Jump to bottom Edit New page
Gordon Potter edited this page Sep 21, 2013 · 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 Installation Troubleshooting 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.

Installation Troubleshooting

Depending on environment settings some users may experience issues getting npm and grunt up and running.

Installing npm modules with your project

Ideally, specific npm modules should be bundled and installed with the project itself. This makes your project more portable.

After you have downloaded a copy of Ember App Kit you need to run the npm install command. This will download and install a variety of modules in a special sub folder of your project folder called node_modules. Here you will find the source code for various external libraries that EAK relies upon.

If there is a new package you want to add to the project be sure to use the --save-dev flag to ensure that the module is installed in the local node_modules folder.

npm install MODULE_NAME --save-dev

For example:

  • npm install grunt-cli --save-dev
  • npm install bower --save-dev

Installing NPM packages in your user account without administrator privileges on your system without sudo

Occasionally you might have a need to install certain modules global to your user account outside your project folder. You might want to do this is you have customized your system and bin paths. In some cases you might not want to install packages with administrator privileges. If you would like install node packages like grunt without administrator privileges, e.g. without using sudo then you can change the npm prefix.

npm set prefix ~/npm

This command will configure npm to install its packages in an npm folder in your home directory owned by your user account. You will need to make sure the bin and lib folders are in your PATH.

PATH=$PATH:$HOME/npm
PATH=$PATH:$HOME/npm/bin
PATH=$PATH:$HOME/npm/lib

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

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