By Justin Gordon and the Shaka Code Team, http://www.shakacode.com
- If you came to here from the blog article, this example project has evolved. See pull requests.
- If this work interests you and you are looking for full or part-time remote work, please click here.
- Please email us at [email protected] if you have a ReactJs + Rails project and are interested in help from our experienced team.
- Please file issues for problems and feature requests.
- Pull requests are welcome! (and a great way to get on the team)
- Feel free to open discussions at forum.railsonmaui.com.
- We now have a gitter chat room for this topic.
- Check out the react_on_rails gem for easy webpack integration.
A Full tutorial article can be found at: Fast Rich Client Rails Development With Webpack and the ES6 Transpiler
Note, this source code repository is way ahead of the tutorial. We plan to update the tutorial as soon as can catch our breath!
Discussion forum regarding the tutorial
This is a simple example application that illustrates the use of ReactJs to implement a commenting
system. Front-end code leverages both ReactJs and Rails asset pipeline while the backend is 100% Rails.
It shows off a little bit of the interactivity of a ReactJs application, allowing the commmenter to
choose the form layout. react-bootstrap
is used for the React components.
A pure Rails UI generated from scaffolding is shown for comparison.
You can see this tutorial live here: http://reactrails.com/
In no particular order:
- Example of using the react_on_rails
- Example of Rails 4.2 with ReactJs/Redux with Webpack and ES7.
- Enable development of a JS client independently from Rails using Webpack Hot Module Reload. You can see this by starting the app and visiting http://localhost:4000
- Easily enable use of npm modules with a Rails application.
- Easily enable retrofitting such a JS framework into an existing Rails app.
- Enable the use of the JavaScript ES7 transpiler.
- Example setting up Ruby and ES7 linting in a real project.
- Example of thorough use of Ruby and JavaScript linters, and other CI tasks.
See package.json and Gemfile for versions
- React (for front-end app)
- react-bootstrap
- Redux
- Webpack with hot-reload (for local dev)
- Babel transpiler (https://github.com/babel/babel)
- Rails 4.2 (for backend app)
- Heroku (for deployment)
- Be sure that you have Node installed. I use nvm, with node
version
v5.0
. See this article Updating and using nvm. git clone [email protected]:shakacode/react-webpack-rails-tutorial.git
cd react-webpack-rails-tutorial
- Check that you have Ruby 2.2.3
- Check that you're using the right version of node. Run
nvm list
to check. - Check that you have Postgres installed. Run
which postgres
to check. bundle install
npm install
rake db:setup
foreman start -f Procfile.dev
- Open a browser tab to http://0.0.0.0:3000 for the Rails app example.
- Open a browser tab to http://0.0.0.0:4000 for the Hot Module Replacement Example.
Setup node and run the node server with file server.js
.
cd client
node server.js
Point your browser to http://0.0.0.0:4000.
Save a change to a JSX file and see it update immediately in the browser! Note, any browser state still exists, such as what you've typed in the comments box. That's totally different than Live Reload which refreshes the browser.
Run webpack
to build the JS/CSS bundles and have them saved in the
Rails asset pipeline (app/assets). Although not shown in this tutorial, the
Webpack ExtractTextPlugin can optionally be used to extract the CSS out of
the JS bundle. We've chosen to let Rails handle CSS, SCSS, images, fonts.
cd client
npm run build:dev
client-bundle.js
is generated and saved to app/assets/javascripts
. This is included in the
Rails asset pipeline.
Observe how the bundles are automatically re-generated whenever your JSX changes.
Once the JS bundle has been generated into the Rails asset pipeline, you can start the Rails server.
cd <rails_project_name>
rake db:setup
rails s
Now point your browser to http://0.0.0.0:3000.
Note that it's important to run the Rails server on a different port than the node server.
webpack.client.base.config.js
: Common configuration file to minimize code duplication for client.rails and client.hot.webpack.client.rails.config.js
: Used to generate the Rails bundles for Rails use.webpack.client.hot.config.js
: Used by server.js to run the Webpack Dev server.webpack.server.rails.config.js
: Common configuration file to minimize code duplication between the HMR and Rails configurations.
- Good overview: Pete Hunt's Webpack Howto
- Webpack Docs
Notice that Bootstrap Sass is installed as both a gem and an npm package. When running the Rails app, the bootstrap-sass gem assets are loaded directly through the asset pipeline without going through Webpack.
See app/assets/application.css.scss
.
On the other hand when running the Webpack dev server, the bootrap-sass npm
assets are loaded through Webpack (with help of the bootstrap-sass-loader).
See webpack/webpack.hot.config.js
.
Bootstrap can be customized by hand-picking which modules to load and/or overwriting some of the Sass variables defined by the framework.
If you are not using all the Bootstrap modules then you'll likely want to customize it to avoid loading unused assets. This customization is done in separate files for the Rails app versus the Webpack dev server so it's important to keep these in-sync as you develop your app in parallel using the Rails and the Webpack HMR environments.
- Rails Bootstrap customization file:
app/assets/stylesheets/_bootstrap-custom.scss
- Webpack HMR Bootstrap customization file:
webpack/bootstrap-sass.config.js
If you need to customize some of the Sass variables defined in Bootstrap you can do so by overwriting these variables in a separate file and have it loaded before other Bootstrap modules.
To avoid duplicating this customization between Rails and Webpack HMR,
this custom code has been consolidated under Webpack in
webpack/assets/stylesheets/_bootstrap-variables-customization.scss
and the
webpack/assets/stylesheets
directory has been added to the Rails asset pipeline
search path. See config config/application.rb
. Keep that in mind as you
customize the Bootstrap Sass variables.
To use bourbon take the following steps:
- Install node-bourbon
cd client && npm install --save node-bourbon
- Update bootstrap-sass.js to use the right paths:
// Add this
var bourbonPaths = require('node-bourbon').includePaths;
module.exports = {
// ...
// And update this
styleLoader: 'style-loader!css-loader!sass-loader?imagePath=/assets/images&includePaths[]=' + bourbonPaths,
@import 'bourbon';
Import bourbon from your scss file
Be sure to see assets.rake for how webpack is invoked during asset compilation.
The webpack.rails.config.js
file generates client-bundle.js which is then included
by the Rails asset pipeline.
##jQuery with Rails and Webpack
jQuery and jQuery-ujs are not required within app/assets/javascript/application.js
and have been moved under/client
and managed by npm. The modules are exposed via entry point
by webpack.common.config.js
.
In application.js
, it's critical that any libraries that depend on jQuery come after the inclusion
of the Webpack bundle, such as the twitter bootstrap javascript.
Please refer to Considerations for jQuery with Rails and Webpack for further info.
- The Webpack server loads the images from the symlink of the
app/assets/images
directory. - Since the images are not moved, Rails loads images via the normal asset pipeline features.
- The
image-url
sass helper takes care of mapping the correct directories for images. The image directory for the webpack server is configured by this line:
{ test: /\.scss$/, loader: "style!css!sass?outputStyle=expanded&imagePath=/assets/images"}
The tutorial makes use of a custom font OpenSans-Light. The font files are located
under app/assets/font
and are loaded by both the Rails asset pipeline and
the Webpack HMR server. See the symlink under webpack/assets/fonts
which
points to app/assets/fonts
.
Note that the libsass C library, which is used by the Webpack sass-loader, does not
support the font-url() helper so we use url() instead. See the hack in
webpack/assets/stylesheets/_bootstrap-variables-customization.scss
.
Run the following command in your development environment to invoke both Webpack and Rails.
bundle exec foreman start -f Procfile.dev
They work for both Rails and the Webpack Server!
In order to deploy to heroku, you'll need to run this command once to set a custom buildpack:
heroku config:add BUILDPACK_URL=https://github.com/ddollar/heroku-buildpack-multi.git
This runs the two buildpacks in the .buildpacks
directory.
Also make sure you are running the latest heroku stack, cedar-14, to avoid running into the following issue.
heroku stack:set cedar-14 -a react-webpack-rails-tutorial
To deploy the app on Heroku:
git push heroku master
Default rake task runs feature specs, mocha tests and linting
We have;
- feature tests in /spec/features
- component unit tests in /client/test/
- javascript linting
From the root of the project, you can run all specs+tests+linter with
npm run test
Run the feature specs individually with rspec
.
Run the React unit tests (all .js and .jsx files) from the client
dir with;
cd client
npm run test --silent
In lieu of having mocha --watch
working properly (pull request welcome!), you can have your js tests continually running with watch
npm install -g watch
cd client
watch 'npm run test --silent' test/ app/
Add those lines to your CI scripts after bundle install
npm install
cd client && npm run build:client && npm run build:server
There's a bunch of gotchas with using Jbuilder to create the string version of the props to be sent to the react_on_rails_gem. The main thing is that if you follow the example and call Jbuilder like this, you don't run into a number of issues.
<%= react_component('App', render(template: "/comments/index.json.jbuilder"),
generator_function: true, prerender: true) %>
However, if you try to set the value of the JSON string inside of the controller, then you will run into several issues with rendering the Jbuilder template from the controller. See the notes in this the example code for app/controllers/pages_controller.rb.
Here's the samples of Jbuilder that we use:
json.extract! comment, :id, :author, :text, :created_at, :updated_at
# Specify the partial, as well as the name of the variable used in the partial
json.array! @comments, { partial: "comments/comment", as: :comment }
json.partial! 'comment', comment: @comment
- Default rake task runs tests and linting (yes, repeating this!) (see
ci.rake
) - See file README.md for how to run ESLint and JSCS
- See scripts
scripts/lint
andclient/bin/lint
. - We're using the AirBnb JavaScript style guidelines.
-
I started out trying to make RubyMine and WebStorm catch and fix linting errors. However, I find it faster to just do this with the command line. Your mileage may vary.
-
Create a custom scope like this for RubyMine, named "Inspection Scope"
file[react-rails-tutorial]:/&&!file[react-rails-tutorial]:tmp//&&!file[react-rails-tutorial]:log//&&!file[react-rails-tutorial]:client/node_modules//&&!file[react-rails-tutorial]:client/assets/fonts//&&!file[react-rails-tutorial]:app/assets/fonts//&&!file[react-rails-tutorial]:bin//&&!file[react-rails-tutorial]:app/assets/javascripts//
-
Install the code style and inspection files in client/jetbrains
-
Use the installed inspection settings and new Inspection Scope for code inspection.
-
RubyMine configuration is optional. All linters run from the command line.
Special thanks to JetBrains for their great tools
RubyMine and WebStorm.
The developers of this project use RubyMine at the top level, mostly for Ruby work, and we use
WebStorm opened up to the client
directory to focus on JSX and Sass files.
alias git-cleanup-merged-branches='git branch --merged master | grep -v master | xargs git branch -d'
This project adheres to the Open Code of Conduct. By participating, you are expected to uphold this code.