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