Frails == Modern Front End on Rails

Frails is a modern asset pipeline for Rails, built on Webpack. Its aims are:

  • Follow convention over configuration as much as possible.
  • Tight integration with Rails, without tying you up in knots.
  • Un-opinionated webpack configuration - batteries not included!
  • Full Webpack control without fighting with the likes of Webpacker.
  • Embrace modern front end practices.

PLUS...

  • Side loaded layouts, views and partials.
  • Components
    • React + SSR
    • Ruby/HTML

Installation

Frails is designed to work only within a Rails application, so must be installed in an existing Rails app. It also requires Node.js and a valid package.json file in your app root.

Add this line to your application's Gemfile:

gem 'frails'

And then execute:

$ bundle

Then run the installer:

$ bin/rails frails:install

Usage

Frails tries to keep as close as possible to a standard Webpack setup, so you can run webpack and webpack-dev-server in the usual way. For example, using yarn you can build:

$ yarn webpack

or run the dev server:

$ yarn webpack-dev-server

Rails will proxy requests to any running Webpack dev server.

Using in Tests

Please note that Frails is not designed or intended to be run in your test environment. This would require a full webpack compile on every test run, which would slow your tests down hugely! Instead, I recommend that you test your Javascript independently using the likes of Jest or some other good Javascript test runner.

Webpack Configuration

Frails requires the user of the webpack-assets-manifest webpack plugin in order for its helpers to work correctly. This is because it needs to be able lookup the real paths of assets, and the manifest file provides that data.

module.exports = {
  ...
  plugins: [
    new WebpackAssetsManifest({
      writeToDisk: true,
      entrypoints: true,
      publicPath: true
    })
  ]
}

Rails Helpers

javascript_pack_tag

Just like javascript_include_tag, but will use your webpack assets.

javascript_include_tag 'application'

stylesheet_pack_tag

Just like stylesheet_link_tag, but will use your webpack assets.

stylesheet_pack_tag 'application'

image_pack_tag

Just like image_tag, but will use your webpack assets.

image_pack_tag 'logo.png'

Side Loaded Assets

Frails has the ability to automatically include your Javascript and CSS based on the current layout and/or view. It even supports side loading partials.

Just set the side_load_assets class variable to your ApplicationController, or indeed to any controller.

class ApplicationController < ActionController::Base
  self.side_load_assets = true
end

As an example, given a view at /app/views/pages/home.html.erb, we can create /app/views/pages/home.css and/or /app/views/pages/home.js. These side-loaded assets will then be included automatically in the page.

app/views/pages: ├── home.html.erb
  ├── home.css
  ├── home.js
  ├── _header.html.erb
  ├── _header.css

Make sure you yield the side loaded CSS and JS tags; <%= yield :side_loaded_css %> in your <head>, and <%= yield :side_loaded_js %> at the bottom of the body:

<!DOCTYPE html>
<html>
  <head>
    <title>My App</title>
    <%= yield :side_loaded_css %>
  </head>
  <body>
    <%= yield %> <%= yield :side_loaded_js %>
  </body>
</html>

CSS is included in-line for faster renders, and JS is included as