Hyperloop and webpacker GEM Tutorial

Prerequisites

{ Ruby On Rails }, { hyperloop GEM }

To set up the Hyperloop GEM onto the Ruby On Rails environment, please follow the

The Goals of this Tutorial

We are going to setup the Webpacker GEM and implement a simple HelloWorld app to show how Hyperloop and webpack are running well together.

You can find the final application source code here:

Skills required

Working knowledge of Rails and Hyperloop required

TUTORIAL

Part 1 - Webpacker GEM

Step 1.1 - Installing and setting up the Webpacker GEM:

Update your Gemfile file:

#Gemfile

gem 'webpacker'

Then run:

bundle update

Run the webpacker install generator:

bundle exec rails webpacker:install

Step 1.2 - Adding libraries into Webpack:

Webpacker GEM comes with the the YARN package manager in order to install needed libraries.

We are going to install 4 libraries required by our application: React, React-dom, Bootstrap and Bootswatch theme.

Run these commands:

yarn add react@15.6.2
yarn add react-dom@15.6.2
yarn add bootstrap react-bootstrap
yarn add bootswatch@3.3.7

Step 1.3 - Requiring the libraires

In the app/javascript/packs add the following two files:

//app/javascript/packs/client_and_server.js

ReactDOM = require('react-dom');
React = require('react');
ReactBootstrap = require('react-bootstrap');

//app/javascript/packs/client_only.js

require('bootswatch/superhero/bootstrap.min.css');

Step 1.4 - Letting Webpack know React and ReactDOM are external

React and ReactDOM are being brought in by Hyperloop, so we need to let Webpack know that these libraries are external so we do not end up with more than one copy of React running. Note that you will also need to do this for your production environment.

In the module.export block, add the following to shared.js:

//config/webpack/shared.js

externals: {
       "react": "React",
       "react-dom": "ReactDOM"
   },

Step 1.5 - Building the webpack bundle

You will need to do this step whenever you make any changes to Webpack or add additional libraries though Yarn.

Run the following commands in your console:

rm -rf tmp/cache/
bin/webpack
rake environment

Note in the above, you should always delete your cache before building your webpack assets. rake environment will recompile Hyperloop.

In the future, when you will add a new library with webpack, it can happen that it is not correctly loaded. So, in this case, we advise to delete the node_modules directory, re-install libraires, re-generate the webpack file and clear Hyperloop cache and browser cache:

rm -rf node_modules
yarn
rm -rf tmp/cache
bin/webpack

Clear Browser cache

Step 1.6 - Configuring Rails asset pipeline:

#config/initializers/assets.rb

Rails.application.config.assets.paths << Rails.root.join('public', 'packs').to_s

Step 1.7 - Adding pack files to the asset pipeline:

By using the Hyperloop configuration file we can directly tell our app to include the pack files in the asset pipeline:

#config/initializers/hyperloop.rb

Hyperloop.configuration do |config|
  config.transport = :simple_poller

  # If your Webpacker version DO NOT generate Manifest files
  config.import 'client_and_server'
  config.import 'client_only', client_only: true

  # If your Webpacker version DOES generate Manifest files
  # config.import Webpacker.manifest.lookup("client_and_server.js").split("/").last
  # config.import Webpacker.manifest.lookup("client_only.js").split("/").last
end

In Rails production mode it would be necessary to include the pack files in your application main layout:

#app/views/layouts/application.tml.erb

<%= javascript_pack_tag 'client_and_server' %>

And { set Hyperloop in AUTO-CONFIG MODE = OFF } in order to choose manually which libraries will be imported.

Step 1.8 - Adding CSS pack files to the asset pipeline

Add this line:

//app/assets/stylesheets/application.css

*= require client_only.css

Note: if you prefer that your CSS pack files being directly packed into the client_only.js you can modify the config/webpack/ config files and run the rm -rf tmp/cache/; bin/webpack; rake environment again.

Part 2 - Implementing the helloworld app

Step 2.1 - Creating the Helloworld component

Run the hyperloop generator:

rails g hyper:component Helloworld

You can view the new Component created in /app/hyperloop/components/

Step 2.2 - Updating Helloworld component code

Copy and paste this code into the component file you've just generated:

#/app/hyperloop/components/helloworld.rb

class Helloworld < Hyperloop::Component

  state show_field: false
  state field_value: ""

  render(DIV) do
    show_button
    DIV(class: 'formdiv') do
      show_input
      H1 { "#{state.field_value}" }
    end if state.show_field
  end

  def show_button
    BUTTON(class: 'btn btn-info') do
      state.show_field ? "Click to hide HelloWorld input field" : "Click to show HelloWorld input field"
    end.on(:click) { mutate.show_field !state.show_field }
  end

  def show_input

    H4 do
      span{'Please type '}
      span.colored {'Hello World'}
      span{' in the input field below :'}
      br {}
      span{'Or anything you want (^̮^)'}
    end

    INPUT(type: :text, class: 'form-control').on(:change) do |e|
      state.field_value! e.target.value
    end
  end

  def show_text
    H1 { "#{state.field_value}" }
  end

end

Step 2.3 - Creating the controller

Create a home_controller.rb file, manually or with the command rails g controller Home helloworld --skip-javascripts:

#app/controllers/home_controller.rb

class HomeController < ApplicationController
  def helloworld
  end
end

Step 2.4 - Updating the routes.rb file

#config/routes.rb

root 'home#helloworld'

Step 2.5 - Creating the helloworld view file:

#app/views/home/helloworld.html.erb

<div class="hyperloophelloword">

  <div>
    <%= react_component '::Helloworld', {}, { prerender: true } %>
  </div>

</div>

Step 2.6 - Styling

We will add a Hyperloop logo

#app/views/home/helloworld.html.erb

<div class="hyperloophelloword">

  <img src="https://rawgit.com/ruby-hyperloop/hyperloop-js-helloworld/master/hyperloop-logo-medium-white.png?raw=true">

  <div>
    <%= react_component '::Helloworld', {}, { prerender: true } %>
  </div>

</div>

And load 1 small sample stylesheet :

#app/views/layouts/application.html.erb

<!DOCTYPE html>
<html>
  <head>
    <title>HyperloopRailsHelloworld</title>
    <%= csrf_meta_tags %>

  <link rel="stylesheet" href="https://rawgit.com/ruby-hyperloop/hyperloop-js-helloworld/master/style.css" >

    <%= stylesheet_link_tag    'application', media: 'all', 'data-turbolinks-track': 'reload' %>
    <%= javascript_include_tag 'application', 'data-turbolinks-track': 'reload' %>
  </head>

  <body>
    <%= yield %>
  </body>
</html>

Final step: Running your app:

Start your Rails server and browse http://localhost:3000.

---

You can find the final application source code here:

The best way to get help and contribute is to join our Gitter Chat