-
Notifications
You must be signed in to change notification settings - Fork 230
Getting Started
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.
When you run grunt server you may see the following message:
>> Local Npm module "grunt-cli" not found. Is it installed?
You can ignore this message for the time being, grunt server task should still run despite this message.
If you are an OS X user and you are not able to install or would like to install grunt without administrator privileges, e.g. without sudo then you can change the npm prefix.
npm set prefix ~/npm
This command will configure npm to install its packages in the 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 # Add npm modules to PATH for scripting
PATH=$PATH:$HOME/npm/bin # Add npm modules to PATH for scripting
PATH=$PATH:$HOME/npm/lib # Add npm modules to PATH for scriptinggrunt 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.
Coming in #49: 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.
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.
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.
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 testruns your application's tests once using Google Chrome. It outputs code coverage information to the terminal and intmp/public/coverage. -
grunt test:ciruns your tests in PhantomJS, and is intended primarily for running on a CI server (such as Travis CI). -
grunt test:serveris similar togrunt serverin 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.
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.
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.
These are optional features your app can use.
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.
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.
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).
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.