{"id":13682694,"url":"https://github.com/emberjs/ember-rails","last_synced_at":"2025-10-05T04:37:25.760Z","repository":{"id":2146799,"uuid":"3091591","full_name":"emberjs/ember-rails","owner":"emberjs","description":"Ember for Rails 3.1+","archived":false,"fork":false,"pushed_at":"2018-06-20T13:50:11.000Z","size":18363,"stargazers_count":1353,"open_issues_count":18,"forks_count":251,"subscribers_count":61,"default_branch":"master","last_synced_at":"2025-04-09T21:06:34.082Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/emberjs/ember-rails","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emberjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-01-03T02:48:12.000Z","updated_at":"2025-04-06T08:06:00.000Z","dependencies_parsed_at":"2022-09-09T18:01:27.500Z","dependency_job_id":null,"html_url":"https://github.com/emberjs/ember-rails","commit_stats":null,"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emberjs%2Fember-rails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emberjs%2Fember-rails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emberjs%2Fember-rails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emberjs%2Fember-rails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emberjs","download_url":"https://codeload.github.com/emberjs/ember-rails/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248298356,"owners_count":21080319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T13:01:51.321Z","updated_at":"2025-10-05T04:37:20.723Z","avatar_url":"https://github.com/emberjs.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# ember-rails  [![Build Status](https://secure.travis-ci.org/emberjs/ember-rails.svg?branch=master)](http://travis-ci.org/emberjs/ember-rails) [![Dependency Status](https://gemnasium.com/emberjs/ember-rails.svg)](https://gemnasium.com/emberjs/ember-rails) [![Code Climate](https://codeclimate.com/github/emberjs/ember-rails/badges/gpa.svg)](https://codeclimate.com/github/emberjs/ember-rails)\n\nember-rails makes developing an [Ember.JS](http://emberjs.com/) application much easier in Rails 4.2+.\n\nThe following functionalities are included in this gem:\n- Pre-compiling of your handlebars templates when building your asset pipeline.\n- Inclusion of development and production copies of Ember, [Ember Data](https://github.com/emberjs/data) and [Handlebars](https://github.com/wycats/handlebars.js).\n- Inclusion of [ActiveModel::Serializer](https://github.com/rails-api/active_model_serializers) for integration with Ember Data.\n\nYou can see an example of how to use the gem [here](https://github.com/keithpitt/ember-rails-example). There is also a great tutorial by [Dan Gebhardt](https://twitter.com/#!/dgeb) called \"[Beginning Ember.js on Rails](http://www.cerebris.com/blog/2012/01/24/beginning-ember-js-on-rails-part-1/)\" which is a great read if you're just starting out with Rails and Ember.js.\n\n## Getting started\n* Add the gem to your application Gemfile:\n\n```ruby\ngem 'ember-rails'\n# gem 'ember-source' # You can specify the Ember.js version you want to use.(such as '~\u003e 1.13.0')\n```\n\n* Run `bundle install`\n* Next, generate the application structure:\n\n```shell\n$ rails generate ember:bootstrap\n```\n\n* Restart your server (if it's running)\n\n## Building a new project from scratch\n\nRails supports the ability to build projects from a template source ruby file.\n\nTo build an Ember centric Rails project you can simply type the following into your command line:\n\n```shell\n$ rails new my-app -m https://emberjs.com/edge_template.rb\n```\n\nRead more about [Rails application templates](http://edgeguides.rubyonrails.org/rails_application_templates.html) and take a look at the edge_template.rb [source code](https://github.com/emberjs/website/blob/master/source/edge_template.rb).\n\nNotes:\n\nTo install the latest builds of ember and ember-data. It should be noted that the\nexamples in the [getting started guide](http://emberjs.com/guides/getting-started/)\nhave been designed to use the released version of ember:\n\n```shell\n$ rails generate ember:install\n```\n\nYou'll probably need to clear out your cache after doing this with:\n\n```shell\n$ rake tmp:clear\n```\n\nAlso, ember-rails includes some flags for the bootstrap generator:\n\n```\n--ember-path or -d   # custom ember path\n--skip-git or -g     # skip git keeps\n--javascript-engine  # engine for javascript (js, coffee, em or es6)\n--app-name or -n     # custom ember app name\n```\n\n\n## For CoffeeScript support\n\nAdd coffee-rails to the Gemfile\n```ruby\ngem 'coffee-rails'\n```\n\nRun the bootstrap generator in step 4 with an extra flag instead:\n```shell\n$ rails g ember:bootstrap -g --javascript-engine coffee\n```\n\n## For EmberScript support\n\n[EmberScript](http://www.emberscript.com) is a dialect of CoffeeScript\nwith extra support for computed properties (which do not have to be\nexplicitly declared), the `class` / `extends` syntax, and extra syntax\nto support observers and mixins.\n\nTo get EmberScript support, make sure you have the following in your\nGemfile:\n\n```ruby\ngem 'ember_script-rails', :github =\u003e 'ghempton/ember-script-rails'\n```\n\nYou can now use the flag `--javascript-engine=em` to specify EmberScript\nassets in your generators, but all of the generators will default to\nusing an EmberScript variant first.\n\n## For ES6 support\n\nEmber.js recommends using ES6 syntax.\nIt is supported by [Babel](https://babeljs.io/) via [ember-es6_template](https://github.com/tricknotes/ember-es6_template).\n\nRun the bootstrap generator with an extra flag:\n\n```shell\n$ rails g ember:bootstrap --javascript-engine=es6\n```\n\nNote:\n\nTo use ES6 module in your application, the following configuration is required:\n\n### Single Ember Application\n\nThis is the case for single Ember application in `app/assets/javascripts` (not under the subdirectory).\n\n`my-app.es6`\n``` javascript\nimport Application from 'ember-rails/application';\n\nconst App = Application.extend({\n  // Configure your application.\n});\n\nApp.create();\n```\n\n`import Application from 'ember-rails/application';` and `Application.extend()` is important.\nIt provides customized Ember application to resolve dependencies from ES6 modules instead of `Ember.Application.extend()`.\n\n`application.js`\n``` javascript\n//= require jquery\n//= require ember\n//= require ember-data\n//= require ember-rails/application\n//= require ./my-app\n//= require_self\n\nrequire('my-app'); // Run your Ember.js application\n```\n\n### Multiple Ember Application\n\nThis is the case for multiple Ember application in your Rails application.\n(Or your Ember application is placed in sub directories of `app/assets/javascripts`.)\n\nFirst, you should configure `config.ember.module_prefix` to `nil`.\nTo disable prepending the module prefix to you modules.\n\n`config/application.rb`\n``` ruby\nconfig.ember.module_prefix = nil\n```\n\nSecond, please specify `modulePrefix` to your Ember application.\n\n`my-app/application.module.es6`\n``` javascript\nimport Application from 'ember-rails/application';\nimport loadInitializers from 'ember/load-initializers';\n\nconst App = Application.extend({\n  modulePrefix: 'my-app' // This value should be the same as directory name.\n});\n\nloadInitializers(App, 'my-app');\n\nApp.create();\n```\n\nLast, add your endpoint to where you want to run your Ember application.\n``` javascript\nrequire('my-app'); // Run your Ember.js application\n```\n\n## Configuration Options\n\nThe following options are available for configuration in your application or environment-level\nconfig files (`config/application.rb`, `config/environments/development.rb`, etc.):\n\n| Configuration Option                         | Description                                                                                                         |\n|----------------------------------------------|---------------------------------------------------------------------------------------------------------------------|\n| `config.ember.variant`                       | Determines which Ember variant to use. Valid options: `:development`, `:production`. Defaults to `:production` in production, and `:development` everywhere else.                               |\n| `config.ember.app_name`                      | Specificies a default application name for all generators.                                                          |\n| `config.ember.ember_path`                    | Specifies a default custom root path for all generators.                                                            |\n| `config.ember.module_prefix`                 | Sets module prefix for es6 module. This option is used for only `es6` scripts. Default value: `ember-app`. |\n| `config.ember.prefix_files`                  | Sets some file names to add `config.ember.module_prefix` into its file name as es6 module name. |\n| `config.ember.prefix_dirs`                   | Sets some dir names to add `config.ember.module_prefix` into its directory name as es6 module name. |\n| `config.handlebars.precompile`               | Enables or disables precompilation. Default value: `true`.                                                          |\n| `config.handlebars.templates_root`           | Sets the root path (under `app/assets/javascripts`) for templates to be looked up in. Default value: `\"templates\"`. |\n| `config.handlebars.templates_path_separator` | The path separator to use for templates. Default value: `'/'`.                                                      |\n| `config.handlebars.output_type`              | Configures the style of output (options are `:amd` and `:global`). Default value: `:global`.                        |\n| `config.handlebars.amd_namespace`            | Configures the module prefix for AMD formatted output. Default value: `nil`.                        |\n| `config.handlebars.ember_template`           | Default which Ember template type to compile. Valid options: `'Handlebars', `HTMLBars`. Defaults to 'Handlebars`' when `Ember::VERSION` is under 1.10.0, `HTMLBars` when `Ember::VERSION` is over 1.10.0. |\n\nNote:\n\nIn a mountable engine, ember-rails will not recognize any configurations.\nInstead, use command line options.\n\n## Enabling Features with Feature Flags\nSee [the guide](http://emberjs.com/guides/configuring-ember/feature-flags/#toc_flagging-details) and check [features.json](https://github.com/emberjs/ember.js/blob/master/features.json) for the version of Ember you're using.\n\nIf a feature is set to false, you will need to compile ember from source yourself to include it.\n\n### Important note for projects that render JSON responses\n\nember-rails includes [active_model_serializers](https://github.com/rails-api/active_model_serializers) which affects how ActiveModel and ActiveRecord objects get serialized to JSON, such as when using `render json:` or `respond_with`. By default active_model_serializers adds root elements to these responses (such as adding `{\"posts\": [...]}` for `render json: @posts`) which will affect the structure of your JSON responses.\n\nTo disable this effect on your JSON responses, put this in an initializer:\n```Ruby\n# Stop active_model_serializers from adding root elements to JSON responses.\nActiveModel::Serializer.root = false\nActiveModel::ArraySerializer.root = false\n```\n\nSee the [active_model_serializers](https://github.com/rails-api/active_model_serializers) documentation for a more complete understanding of other effects this dependency might have on your app.\n\n## Architecture\n\nEmber does not require an organized file structure. However, ember-rails allows you\nto use `rails g ember:bootstrap` to create the following directory structure under `app/assets/javascripts`:\n\n```\n├── adapters\n├── components\n├── controllers\n├── helpers\n├── mixins\n├── models\n├── practicality.coffee\n├── router.coffee\n├── routes\n├── templates\n│   └── components\n└── views\n```\n\nAdditionally, it will add the following lines to `app/assets/javascripts/application.js`.\nBy default, it uses the Rails Application's name and creates an `rails_app_name.js`\nfile to set up application namespace and initial requires:\n\n```javascript\n//= require ember\n//= require ember-data\n//= require_self\n//= require rails_app_name\nRailsAppName = Ember.Application.create();\n```\n\n*Example:*\n\n```shell\n$ rails g ember:bootstrap\n  insert  app/assets/javascripts/application.js\n  create  app/assets/javascripts/models\n  create  app/assets/javascripts/models/.gitkeep\n  create  app/assets/javascripts/controllers\n  create  app/assets/javascripts/controllers/.gitkeep\n  create  app/assets/javascripts/views\n  create  app/assets/javascripts/views/.gitkeep\n  create  app/assets/javascripts/helpers\n  create  app/assets/javascripts/helpers/.gitkeep\n  create  app/assets/javascripts/components\n  create  app/assets/javascripts/components/.gitkeep\n  create  app/assets/javascripts/templates\n  create  app/assets/javascripts/templates/.gitkeep\n  create  app/assets/javascripts/templates/components\n  create  app/assets/javascripts/templates/components/.gitkeep\n  create  app/assets/javascripts/mixins\n  create  app/assets/javascripts/mixins/.gitkeep\n  create  app/assets/javascripts/adapters\n  create  app/assets/javascripts/adapters/.gitkeep\n  create  app/assets/javascripts/app.js\n```\n\nIf you want to avoid `.gitkeep` files, use the `skip git` option like\nthis: `rails g ember:bootstrap -g`.\n\nAsk Rails to serve HandlebarsJS and pre-compile templates to Ember\nby putting each template in a dedicated \".hbs\", \".js.hjs\" or \".handlebars\" file\n(e.g. `app/assets/javascripts/templates/admin_panel.hbs`)\nand including the assets in your layout:\n\n```erb\n\u003c%= javascript_include_tag \"templates/admin_panel\" %\u003e\n```\n\nIf you want to avoid the `templates` prefix, set the `templates_root` option in your application configuration block:\n\n```ruby\nconfig.handlebars.templates_root = 'ember_templates'\n```\n\nIf you store templates in a file like `app/assets/javascripts/ember_templates/admin_panel.hbs` after setting the above config,\nit will be made available to Ember as the `admin_panel` template.\n\n_(Note: you must clear the local sprockets cache after modifying `templates_root`, stored by default in `tmp/cache/assets`)_\n\nDefault behavior for ember-rails is to precompile handlebars templates.\nIf you don't want this behavior you can turn it off in your application configuration (or per environment in: `config/environments/development.rb`) block:\n\n```ruby\nconfig.handlebars.precompile = false\n```\n\n_(Note: you must clear the local sprockets cache if you disable precompilation, stored by default in `tmp/cache/assets`)_\n\nBundle all templates together thanks to Sprockets,\ne.g create `app/assets/javascripts/templates/all.js` with:\n\n```js\n//= require_tree .\n```\n\nNow a single line in the layout loads everything:\n\n```erb\n\u003c%= javascript_include_tag \"templates/all\" %\u003e\n```\n\n### Note about ember components\n\nWhen necessary, ember-rails adheres to a conventional folder structure. To create an ember component you must define the handlebars file *inside* the *components* folder under the templates folder of your project to properly register your handlebars component file.\n\n*Example*\n\nGiven the following folder structure:\n\n```\n├── adapters\n├── components\n├── controllers\n├── helpers\n├── mixins\n├── models\n├── practicality.coffee\n├── router.coffee\n├── routes\n├── templates\n│   └── components\n│       └── my-component.hbs\n└── views\n```\n\nand a `my-component.hbs` file with the following contents:\n\n```hbs\n\u003ch1\u003eMy Component\u003c/h1\u003e\n```\n\nIt will produce the following handlebars output:\n\n```html\n\u003cscript type=\"text/x-handlebars\" id=\"components/my-component\"\u003e\n  \u003ch1\u003eMy Component\u003c/h1\u003e\n\u003c/script\u003e\n```\n\nYou can reference your component inside your other handlebars template files by the handlebars file name:\n\n```hbs\n{{ my-component }}\n```\n\n## Specifying Different Versions of Ember/Handlebars/Ember-Data\n\nBy default, ember-rails ships with the latest version of\n[Ember](https://rubygems.org/gems/ember-source/versions),\n[Handlebars](https://rubygems.org/gems/handlebars-source/versions),\nand [Ember-Data](https://rubygems.org/gems/ember-data-source/versions).\n\nTo specify a different version that'll be used for both template\nprecompilation and serving to the browser, you can specify the desired\nversion of one of the above-linked gems in the Gemfile, e.g.:\n\n```ruby\ngem 'ember-source', '~\u003e 1.13.0'\n```\n\nYou can also specify versions of 'handlebars-source' and\n'ember-data-source', but note that an appropriate 'handlebars-source'\nwill be automatically chosen depending on the version of 'ember-source'\nthat's specified.\n\nYou can also override the specific ember.js, handlebars.js, and\nember-data.js files that'll be `require`d by the Asset pipeline by\nplacing these files in `vendor/assets/ember/development` and\n`vendor/assets/ember/production`, depending on the `config.ember.variant`\nyou've specified in your app's configuration, e.g.:\n\n```ruby\nconfig.ember.variant = :production\n# config.ember.variant = :development\n```\n\n## Updating Ember\n\nIf at any point you need to update Ember.js from any of the release channels, you can do that with\n\n```shell\n$ rails generate ember:install --channel=\u003cchannel\u003e\n```\n\nThis will fetch both Ember.js and Ember Data from [http://builds.emberjs.com/](http://builds.emberjs.com/) and copy to the right directory. You can choose between the following channels:\n* canary - This references the 'master' branch and is not recommended for production use.\n* beta - This references the 'beta' branch, and will ultimately become the next stable version. It is not recommended for production use.\n* release - This references the 'stable' branch, and is recommended for production use.\n\nWhen you don't specify a channel, the release channel is used.\n\nIt is also possible to download a specific tagged release. To do this, use the following syntax:\n\n```shell\n$ rails generate ember:install --tag=v1.13.0 --ember\n```\n\nor for ember-data\n\n```shell\n$ rails generate ember:install --tag=v1.13.0 --ember-data\n```\n\n## CSRF Token\n\nRails [`protect_from_forgery`](http://api.rubyonrails.org/classes/ActionController/RequestForgeryProtection/ClassMethods.html#method-i-protect_from_forgery) requires CSRF token for every XHR except GET.\nThe CSRF token is normally found in `app/views/layouts/application.html.*` inserted with the rails helper: [`csrf_meta_tags`](http://api.rubyonrails.org/classes/ActionView/Helpers/CsrfHelper.html#method-i-csrf_meta_tags).\n\nWhen you use [jquery-ujs](https://github.com/rails/jquery-ujs),\nthe CSRF token will be sent to the rails application on every XHR automatically.\nIf not so, the following JavaScript is required in your code.\n\n``` javascript\n$.ajaxPrefilter(function(options, originalOptions, xhr) {\n  var token = $('meta[name=\"csrf-token\"]').attr('content');\n  xhr.setRequestHeader('X-CSRF-Token', token);\n});\n```\n\n## Note on Patches/Pull Requests\n\n1. Fork the project.\n2. Make your feature addition or bug fix.\n3. Add tests for it. This is important so I don't break it in a future version unintentionally.\n4. Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)\n5. Send me a pull request. Bonus points for topic branches.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femberjs%2Fember-rails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femberjs%2Fember-rails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femberjs%2Fember-rails/lists"}