README.md in ember-cli-rails-0.6.0 vs README.md in ember-cli-rails-0.6.1

- old
+ new

@@ -11,14 +11,18 @@ applications and your API from a single domain * Write truly end-to-end integration tests, exercising your application's entire stack through JavaScript-enabled Capybara tests * Deploy your entire suite of applications to Heroku with a single `git push` -**EmberCLI-Rails Supports EmberCLI 1.13.x and later.** +If you're having trouble, checkout the [example project]! -## Installation +**EmberCLI-Rails Supports EmberCLI 1.13.13 and later.** +[example project]: https://github.com/seanpdoyle/ember-cli-rails-heroku-example + +## Install + Add the following to your `Gemfile`: ```ruby gem "ember-cli-rails" ``` @@ -27,12 +31,18 @@ ```bash $ bundle install ``` -## Usage +If you haven't created an Ember application yet, generate a new one: +```bash +$ ember new frontend --skip-git +``` + +## Setup + First, generate the gem's initializer: ```bash $ rails generate ember:init ``` @@ -45,29 +55,23 @@ EmberCli.configure do |c| c.app :frontend end ``` -The initializer assumes that your Ember application exists in +This initializer assumes that your Ember application exists in `Rails.root.join("frontend")`. If this is not the case, you could * move your existing Ember application into `Rails.root.join("frontend")` -* configure `frontend` to look for the Ember application in its current +* configure `frontend` to reference the Ember application in its current directory: ```rb c.app :frontend, path: "~/projects/my-ember-app" ``` -* generate a new Ember project: - -```bash -$ ember new frontend --skip-git -``` - **Initializer options** - `name` - this represents the name of the Ember CLI application. - `path` - the path where your Ember CLI application is located. The default @@ -103,23 +107,22 @@ ``` [addon]: https://github.com/rondale-sc/ember-cli-rails-addon/ [semver]: http://semver.org/ -Next, configure Rails to route requests to the `frontend` Ember application: +## Mount +Configure Rails to route requests to the `frontend` Ember application: + ```rb # config/routes.rb Rails.application.routes.draw do mount_ember_app :frontend, to: "/" end ``` -Ember requests will be set `params[:ember_app]` to the name of the application. -In the above example, `params[:ember_app] == :frontend`. - **Routing options** * `to` - The path to handle as an Ember application. This will only apply to `format: :html` requests. Additionally, this will handle child routes as well. For instance, mounting `mount_ember_app :frontend, to: "/frontend"` will handle a @@ -134,12 +137,74 @@ ``` Boot your Rails application, navigate to `"/"`, and view your EmberCLI application! -## Heroku +## Develop +EmberCLI Rails exposes several useful rake tasks. + +**`ember:install`** + +Install the Ember applications' dependencies. + +**`ember:compile`** + +Compile the Ember applications. + +**`ember:test`** + +Execute Ember's test suite. + +If you're using Rake to run the test suite, make sure to configure your test +task to depend on `ember:test`. + +For example, to configure a bare `rake` command to run both RSpec and Ember test +suites, configure the `default` task to depend on both `spec` and `ember:test`. + +```rb +task default: [:spec, "ember:test"] +``` + +## Deploy + +In production environments, assets should be served over a +Content Delivery Network. + +Configuring an `ember-cli-rails` application to serve Ember's assets over a CDN +is very similar to [configuring an EmberCLI application to serve assets over a +CDN][ember-cli-cdn]: + +[ember-cli-cdn]: http://ember-cli.com/user-guide/#fingerprinting-and-cdn-urls + +```js +var app = new EmberApp({ + fingerprint: { + prepend: 'https://cdn.example.com/' + } +}); +``` + +If you're serving the Ember application from a path other than `"/"`, the +`prepend` URL must end with the mounted path: + +```js +var app = new EmberApp({ + fingerprint: { + // for an Ember application mounted to `/admin_panel/` + prepend: 'https://cdn.example.com/admin_panel/', + } +}); +``` + +As long as your [CDN is configured to pull from your Rails application][dns-cdn] +, your assets will be served over the CDN. + +[dns-cdn]: https://robots.thoughtbot.com/dns-cdn-origin + +### Heroku + To configure your EmberCLI-Rails applications for Heroku: 1. Execute `rails generate ember:heroku` 1. [Add the NodeJS buildpack][buildpack] and configure NPM to include the `bower` dependency's executable file. @@ -161,12 +226,37 @@ **NOTE** Run the generator each time you introduce additional EmberCLI applications into the project. [buildpack]: https://devcenter.heroku.com/articles/using-multiple-buildpacks-for-an-app#adding-a-buildpack -## Overriding the defaults +### Capistrano +EmberCLI-Rails executes both `npm install` and `bower install` during EmberCLI's +compilation, triggered by the `asset:precompilation` rake task. + +The `npm` and `bower` executables are required to be defined in the deployment +SSH session's `$PATH`. It is not sufficient to modify the session's `$PATH` in +a `.bash_profile`. + +To resolve this issue, prepend the Node installation's `bin` directory to the +target system's `$PATH`: + +```ruby +#config/deploy/production.rb + +set :default_env, { + "PATH" => "/home/deploy/.nvm/versions/node/v4.2.1/bin:$PATH" +} +``` + +The system in this example is using `nvm` to configure the node version. If +you're not using `nvm`, make sure the string you prepend to the `$PATH` variable +contains the directory or directories that contain the `bower` and `npm` +executables. + +## Override + By default, routes defined by `ember_app` will be rendered with the internal `EmberCli::EmberController`. ### Overriding the view @@ -233,11 +323,11 @@ render layout: false end end ``` -#### Rendering the EmberCLI generated JS and CSS +### Rendering the EmberCLI generated JS and CSS Rendering EmberCLI applications with `render_ember_app` is the recommended, actively supported method of serving EmberCLI applications. However, for the sake of backwards compatibility, `ember-cli-rails` supports @@ -251,13 +341,13 @@ ```erb <%= include_ember_script_tags :frontend %> <%= include_ember_stylesheet_tags :frontend %> ``` -### Mounting the Ember applications +### Mounting multiple Ember applications -Rendering Ember applications from routes other than `/` requires additional +Rendering Ember applications to paths other than `/` requires additional configuration. Consider a scenario where you had Ember applications named `frontend` and `admin_panel`, served from `/` and `/admin_panel` respectively. @@ -337,18 +427,31 @@ When injecting the EmberCLI-generated assets with the `include_ember_script_tags` and `include_ember_stylesheet_tags` helpers to a path other than `"/"`, a `<base>` tag must also be injected with a corresponding `href` value: ```erb +<base href="/"> <%= include_ember_script_tags :frontend %> <%= include_ember_stylesheet_tags :frontend %> <base href="/admin_panel/"> <%= include_ember_script_tags :admin_panel %> <%= include_ember_stylesheet_tags :admin_panel %> ``` +If you're using the `include_ember` style helpers with a single-page Ember +application that defers routing to the Rails application, insert a call to +`mount_ember_assets` at the bottom of your routes file to serve the +EmberCLI-generated assets: + +```rb +# config/routes.rb +Rails.application.routes.draw do + mount_ember_assets :frontend, to: "/" +end +``` + ## CSRF Tokens Your Rails controllers, by default, expect a valid authenticity token to be submitted along with non-`GET` requests. @@ -375,36 +478,10 @@ the CSRF tags to its view's `<head>`. [ember-cli-rails-addon][addon] configures your Ember application to make HTTP requests with the injected CSRF tokens in the `X-CSRF-TOKEN` header. -### Integrating with Rake - -EmberCLI Rails exposes several useful rake tasks. - -**`ember:install`** - -Install the Ember applications' dependencies. - -**`ember:compile`** - -Compile the Ember applications. - -**`ember:test`** - -Execute Ember's test suite. - -If you're using Rake to run the test suite, make sure to configure your test -task to depend on `ember:test`. - -For example, to configure a bare `rake` command to run both RSpec and Ember test -suites, configure the `default` task to depend on both `spec` and `ember:test`. - -```rb -task default: [:spec, "ember:test"] -``` - ## Serving from multi-process servers in development If you're using a multi-process server ([Puma], [Unicorn], etc.) in development, make sure it's configured to run a single worker process. @@ -413,11 +490,11 @@ [Puma]: https://github.com/puma/puma [Unicorn]: https://rubygems.org/gems/unicorn [#94]: https://github.com/thoughtbot/ember-cli-rails/issues/94#issuecomment-77627453 -### `RAILS_ENV` +## `RAILS_ENV` While being managed by EmberCLI Rails, EmberCLI process will have access to the `RAILS_ENV` environment variable. This can be helpful to detect the Rails environment from within the EmberCLI process. @@ -438,9 +515,15 @@ ``` `RAILS_ENV` will be absent in production builds. [ember-cli-mirage]: http://ember-cli-mirage.com/docs/latest/ + +## EmberCLI support + +This project supports: + +* EmberCLI versions `>= 1.13.13` ## Ruby and Rails support This project supports: