By Justin Gordon and the Shaka Code Team, http://www.railsonmaui.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 justin@shakacode.com 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 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:3000
- 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
v0.12.7. See this article Updating and using nvm. git clone git@github.com:shakacode/react-webpack-rails-tutorial.gitcd react-webpack-rails-tutorial- Check that you have Ruby 2.2.2
- Check that you're using the right version of node. Run
nvm listto check. - Check that you have Postgres installed. Run
which postgresto check. bundle installnpm installrake db:setupforeman start -f Procfile.dev- Open a browser tab to http://0.0.0.0:4000 for the Rail app example.
- Open a browser tab to http://0.0.0.0:3000 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:3000.
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 bin)/webpack -w --config webpack.rails.config.js
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 -p 4000
Now point your browser to http://0.0.0.0:4000.
Note that it's important to run the Rails server on a different port than the node server.
webpack.hot.config.js: Used by server.js to run the demo HMR server.webpack.rails.config.js: Used to generate the Rails bundles.webpack.common.config.js: Common configuration file to minimize code duplication between the HMR and Rails configurations.
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.
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/imagesdirectory. - Since the images are not moved, Rails loads images via the normal asset pipeline features.
- The
image-urlsass 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 tests and linting
We have feature tests in /spec/features
Run the tests with rspec.
- 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/lintandclient/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.