(my) Best Practices for Aurelia - Adding to Ruby on Rails

If you're reading this chances are you have at least some familiarity with Ruby on Rails. If not I would recommend checking out some of the available tutorials on RoR before thinking about following along.

New Project

Let's create our new rails app aureliawesome

$ rails new aureliawesome

I could focus on adding testing and everything we actually need in a Rails app but there are numerous resources already available on the topic so for the purpose of this post we will continue on to adding Aurelia.

Adding aurelia

Now we have a rails app let's add the assets we need. For this introduction we will be starting with the skeleton-navigation app as a base.

Go to the javascripts folder
$ cd app/assets/javascripts
Starting with a fresh skeleton

As always let's get an Aurelia app running.

Begin by download the navigation skeleton. Then we need to do some basic setup at the root of that project directory.

$ jspm registry config github
$ npm install
$ jspm install -y

$ gulp watch

Now we have our app being served @ localhost:9000

Add a controller/view to serve our app

In the spirit of a single page app here we will create a single controller and view to serve our aurelia application. It should be noted that if you choose to have several pages serve the same app or have seperate apps load shared content this is really easy to set up with Aurelia! I will cover this in my next post.

Return to RoR project root in your terminal session

If you are still in the javascripts folder this can be accomplished with -

$ cd ../../..
Create controller/view
$ rails generate controller welcome index

Now let's set our index view to serve our aureliawesome app (note: I use slim here (slim, slim-rails), but use erb or html or whatever your heart desires) -

index.html.slim -

h1 Welcome#index  
p Find me in app/views/welcome/index.html.slim  
section aurelia-app=""

= javascript_include_tag 'aureliawesome-app/jspm_packages/system.js'
= javascript_include_tag 'aureliawesome-app/config.js'

javascript:  
  System.import('aurelia-bootstrapper');

The section aurelia-app="" is where our app will be injected. The include tags for the JavaScript files load the system.js module loader and our custom config.js tells system.js where to find everything. Finally, we call System.import('aurelia-bootstrapper') to tell system.js to use the bootstrapper plugin to load the application.

Add our js files to the asset pipeline

This step is optional and depends heavily on how you want to have your aurelia app available. I am going to use this method until a better one comes up :)

In config/initializers/assets.rb add our config.js and system.js -

Rails.application.config.assets.precompile += %w( aureliawesome-app/jspm_packages/system.js )  
Rails.application.config.assets.precompile += %w( aureliawesome-app/config.js )  

If you do update the config file make sure to restart your rails server

Set the baseURL for where our files are served

Since we are adding the app into the JavaScripts folder we need to tell System.js where to find it's dependencies. We do this in the config.js located in our app/assets/javascripts/aureliawesome-app directory. Adjust the config.js to match below -

System.config({  
  "baseURL": "/assets/aureliawesome-app",
  "paths": {
    "*": "dist/*.js",
    "github:*": "jspm_packages/github/*.js",
    "npm:*": "jspm_packages/npm/*.js",
    "aurelia-skeleton-navigation/*": "lib/*.js"
  }
});

Bring up rails server

Make sure our terminal session is at the project root and lets bring up a rails server -

$ rails s

Now in our browser let's navigate to our app localhost:3000/welcome/index

That should be it! If you have any issues please let me know ASAP!

Improving our process

We are currently looking at the best way to improve the developer experience. Because we are in an alpha state please remember that there are breaking changes still occurring so be prepared to update.

Please feel free to improve this set up at this repo - https://github.com/PWKad/aurelia-rails - or open any issues you run into there or in the appropriate repository for Aurelia.