So, you’re a Rails developer, and you started to play with Vue (maybe using the CDN / ES5 way?), everything looks so exciting, you’re even thinking about using it in your next project. Great! And then problems start to pop up. How do I structure my files? How do I implement I18n? What about authentication? Pagination?… Surprisingly, I did not found a lot of resources related to Vue + Webpack + Rails, so I thought it might be a good idea to share some of the solutions I came up with.
You’ll find a demo app repository here, so you could play with the code and test it out.
1. The specs
Let’s start with what I really wanted for this demo project:
- A user should be able to reload any page at any time. Same for the back button that should just work
- I18n is important, and it should be simple. Translations files are also rapidly growing up in a real app, we should be able to handle this in a real world scenario
- Pagination should work hand in hand with Kaminari
- Authentication, to access an Admin section
- Dynamic filters are mandatory in any Admin section, we should be able to use Ransack
- ActionCable is great, we should also handle it
2. Opinions and tools
- With Sprockets not being able to deal with ES6 code nor .vue files, we’ll have to use Webpack. Perfect timing, it has just been integrated in Rails a few months ago.
- The directory tree of Javacript files should be scalable and easy to grasp. Maintainability above everything.
- Client side generated routes must match with the ones you’d get in regular Rails app, let’s avoid headaches
- Avoid installing JS dependencies and plugins, as much as possible, except for what’s officially supported/required by Vue
- Since most (actually: all) of the projects I work with are using Bootstrap, where it is required, let’s use good ol’ JQuery for AJAX requests
- CSS will be handled by the asset pipeline, “the classical way”. Although you can add CSS inside of your .vue files, I can’t find a single use case where it would be
usefula good idea in the Web apps I build
- Vuex simplifies a lot of things, let’s use it
- Components should not perform AJAX calls directly. Components should take care of “view layout + behavior”, and nothing else
- Strictly speaking, server side generated JSON is an “API”, but I won’t build a pure RESTfull “API” here. I choose JSON builder for the demo, primarily because it is simple to actually see the JSON structure in the code, but feel free to use whatever tool is best for you. Anyway, I tend to think an “SPA back-end” != “public API”, but that’s another debate
3. How it works
Admitting you already initialized your Rails project with:
rails new myapp --webpack=vue
3.1 Base directory structure
1 2 3 4 5 6 7 8 9 10 11 12
/javacript /packs /components /home index.vue /filters string.js /vuex /stores index.js /application.js /routes.js
components: will be structured quite close to what it would have been in the “view” rails dir, and will contains, well… components. Basically, your “.vue” files.
filters: more or less like “helpers”, in the Rails world. I use it to format strings, dates… more about filters here.
vuex: the “index.js” file is used to register stores and is mostly populated with “import” statements. On the other hand, the stores directory hosts all, namespaced, stores.
application.js: the main JS application boot loader, where you setup what you’re going to use in the app (router, I18n…). This is where you setup I18n, and I also use this file to setup JQuery’s AJAX calls
routes.js: all of the routes for this app
3.2 Loading the app
3.3 Server side routing
At the very beginning of the project, routes are quite simple :
1 2 3 4 5 6 7 8 9 10
Rails.application.routes.draw do namespace :api do resources :dashboard, only: [:index] end root :to => "application#index" match "*path", to: "application#index", format: false, via: :get end
Simple: plain ol’ Devise. Since this SPA is made to be loaded from a browser, there’s no need to complicate things using JWT or OAuth for now. Authentication Data will be stored in a session cookie, which will be sent within AJAX requests.
3.5 Adding a sub section (aka: and admin section)
1 2 3 4 5 6 7 8 9 10 11 12 13
/javacript /packs /admin /components /filters /vuex /application.js /routes.js /components /filters /vuex /application.js /routes.js
Basically, what we’re doing here is to create a totally separated “app”, from a JS point of view. Doing it this way, you will load the Admin related stuff, and only the admin stuff. That means: routes, components, stores and while we’re at it: translations. How do we load this JS app? Quite like we did for the front-end, but this time we’ll use admin.html.erb.
3.6 File names conventions
Let’s have a quick look at what’s inside the demo’s component directory:
1 2 3 4 5 6 7 8 9
/javacript /packs /admin /components /musicians _form.vue edit.vue index.vue new.vue
Feels familiar, isn’t it? Classical names apply perfectly here, too. Files like “index.vue” or “edit.vue” are higher order components (aka: pages), where you import child components, underscore prefixed (aka: partials in the “old world”).
If you don’t know what Vuex is, I would highly recommend to watch those 2 videos. So, yes, let’s use Vuex to handle all AJAX calls, as well as all state loads and modifications. If components may be seen like “views + behaviour”, you can see a store quite like “controller + model”. Controller because it handles the requests, and Model because it is manipulating the Data. Ok, ok, I know it’s silly to try translating 1:1 Rails MVC to Vue, but if it may help you to understand how it globally works, let’s see it this way to get started.
Ok, so, what’s in a Store? Basically: this. Aside from the obvious actions and mutations, you will sometime notice 2 extra mutations: progress and errors when I use forms. This leads us directly to the next section:
3.8 User interaction
One thing that is quite disturbing working with an SPA is that the browser is not helping us. There’s no spinner at the top of the tab, and the page is not passing through the “click -> spinner is spinning -> refresh -> blank page -> repaint” cycle. Nonetheless, we have to take care of our user, and let him understand what’s going on when submitting a form. That’s why I created 2 extra mutations in stores that are using a form:
- progress: variable to track the current state of the request (start / loading / success / failed)
- errors: calls a little helper to show up form errors
A bit of CSS on top of that and now your users understand what’s happening. You also avoid multiple form submissions, and this is not just a designer’s whim.
Pagination is made using a component, client side, as well as adding a short snippet in the server side generated JSON. Drop this component in a “/components/shared” directory, and now all you have to do is calling this in some parent component when you need it:
(Mmh, that’s a lot of “pagination” for just one line. Don’t worry, you’ll found this pattern pretty common when passing data down to components).
3.10 Ransack and dynamic filters
Quite like for pagination, the base idea is to sequentially:
- Update the query string using user parameters on form submission
- When a URL change is detected, call an action in the store using the Query string as an argument
- Request data from the server using this URL / Query string
- Finally, mutate the state with the data you just got back from server
What is a bit tricky here is that Vue sees query strings using arrays as JS Objects, so I had to tweak query string construction a little bit. In the end I got it working, now you just have to follow the steps to reuse this component to fit your needs.
3.11 ActionCable and Vue
You have to set things up exactly the same way you’d do in a classical app, the only thing we’re going to add here is about informing Vue when new messages are coming. This is done using an Event Bus. With this Event Bus mounted, the chat component will be notified each time there is a new event. On the other side, when you want to push new messages out, simply use the globally accessible “App” Object you created in the asset pipeline’s powered channel.
4. Packing it up
Wow, that’s quite a lot of stuff for a blog post! I really encourage you to clone the demo repo and play with the code.
Now, if I had to summarize my thoughts about building a Single Page Apps with Rails + Vue.js + Webpacker, three things would come up:
Rails is an awesome starting point for an SPA: I read sooooo many tutorials and blog posts about configuring Webpack that I was stuck with this one question: “how and where do I actually start?”. Now, with Webpacker and Yarn included right in the Framework, there’s nothing to fear, everything works out of the box. Testing is also improved, since you can now test each.and.every.part of the backend, no need to spin up utter slow layers like Selenium to test views output, and testing JSON is trivial.
Vue is a fabulous JS framework: I feel like it has picked up the best ideas from React (Component based, Flux pattern) and the best ideas from Angular (templates with custom markup, eg: v-if, v-for…). Using Webpack to compile .vue files and Vuex, in the end, I managed to get something fully scalable as my code grows, and really maintainable with not that much of code, compared to a classical app.