Webpacker-React makes it easy to use React with Webpacker in your Rails applications.
Important note: Webpacker is not yet officially released. It will be included in Rails 5.1 but is highly experimental for now.
An example application is available: https://github.com/renchap/webpacker-react-example/
This gem is a work in progress. Final feature list:
- uses the new Webpacker way of integrating Javascript with Rails (using packs)
- render React components from views using a
react_component
helper - render React components from controllers using
render react_component: 'name'
- support for hot reloading
- render components server-side
- use a Rails generator to create new components
Your Rails application needs to use Webpacker and have the React integration done. Please refer to their documentation documentation for this: https://github.com/rails/webpacker/blob/master/README.md#ready-for-react
First, you need to add the webpacker-react gem to your Rails app Gemfile:
gem 'webpacker-react', "~> 0.1.0"
Once done, run bundle
to install the gem.
Then you need to update your package.json
file to include the webpacker-react
NPM module:
./bin/yarn add webpacker-react
You are now all set!
Webpacker-React contains two parts: a Javascript module and a Ruby gem. Both of those components respect semantic versioning. When upgrading the gem, you need to upgrade the NPM module to the same minor version. New patch versions can be released for each of the two independently, so it is ok to have the NPM module at version A.X.Y
and the gem at version A.X.Z
, but you should never have a different A
or X
.
The first step is to register your root components (those you want to load from your HTML).
In your pack file (app/javascript/packs/*.js
), import your components as well as webpacker-react
and register them. Considering you have a component in app/javascript/components/hello.js
:
import Hello from 'components/hello'
import WebpackerReact from 'webpacker-react'
WebpackerReact.register(Hello)
WebpackerReact.initialize()
You have to make sure Turbolinks is loaded before calling WebpackerReact.initialize()
.
For example:
import Hello from 'components/hello'
import WebpackerReact from 'webpacker-react'
import Turbolinks from 'turbolinks'
Turbolinks.start()
WebpackerReact.initialize()
WebpackerReact.register(Hello)
You may also load turbolinks in regular asset pipeline application.js
:
//= require "turbolinks"
In that case, make sure your packs are loaded after application.js
Now you can render React components from your views or your controllers.
Use the react_component
helper:
<%= react_component('Hello', name: 'React') %>
class PageController < ApplicationController
def main
render react_component: 'Hello', props: { name: 'React' }
end
end
You can pass any of the usual arguments to render in this call: layout
, status
, content_type
, etc.
Note: you need to have Webpack process your code before it is available to the browser, either by manually running ./bin/webpack
or having the ./bin/webpack-watcher
process running.
HMR allows to reload / add / remove modules live in the browser without reloading the page. This allows any change you make to your React components to be applied as soon as you save, preserving their current state.
First, install react-hot-loader
:
./bin/yarn add [email protected]
You then need to update your Webpack config.
We provide a convenience function to add the necessary changes to your config if it's not significantly different than the standard Webpacker config:
//development.js
...
var configureHotModuleReplacement = require('webpacker-react/configure-hot-module-replacement')
var sharedConfig = require('./shared.js')
sharedConfig.config = configureHotModuleReplacement(sharedConfig.config)
module.exports = merge(sharedConfig, ...)
If you need to change your configuration manually:
-
set the public URL used to load
webpack-dev-server
assets{ output: { publicPath: 'http://localhost:8080' } }
-
add
react-hot-loader/babel
to yourbabel-loader
rules:{ module: { rules: [ { test: /\.jsx?(.erb)?$/, exclude: /node_modules/, loader: 'babel-loader', options: { presets: [ 'react', [ 'latest', { 'es2015': { 'modules': false } } ] ], plugins: ['react-hot-loader/babel'] } } }
-
prepend
react-hot-loader/patch
to your entries:{ entry: { application: [ 'react-hot-loader/patch', '../app/javascript/packs/application.js' ], ... }
-
you now need to use
webpack-dev-server
(in place ofwebpack
orwebpack-watcher
). Make sure the following line is in your development.rb:config.x.webpacker[:dev_server_host] = 'http://localhost:8080/'
and start webpack-dev-server
in hot replacement mode:
./bin/webpack-dev-server --hot
- finally opt in to HMR from your pack files:
import SomeRootReactComponent from 'components/some-root-react-component' import WebpackerReact from 'webpacker-react/hmr' WebpackerReact.register(SomeRootReactComponent) if (module.hot) module.hot.accept('components/some-root-react-component', () => WebpackerReact.renderOnHMR(SomeRootReactComponent) )
To work on this gem locally, you first need to clone and setup the example application.
Then you need to change the example app Gemfile to point to your local repository and run bundle afterwise:
gem 'webpacker-react', path: '~/code/webpacker-react/'
Finally, you need to tell Yarn to use your local copy of the NPM module in this application, using yarn link
:
$ cd ~/code/webpacker-react/javascript/webpacker_react-npm-module/
$ yarn
$ cd dist/
$ yarn # compiles the code from src/ to dist/
$ yarn link
success Registered "webpacker-react".
info You can now run `yarn link "webpacker-react"` in the projects where you want to use this module and it will be used instead.
$ cd ~/code/webpacker-react-example/
$ yarn link webpacker-react
success Registered "webpacker-react".
After launching ./bin/webpack-watcher
and ./bin/rails server
in your example app directory, you can now change the Ruby or Javascript code in your local webpacker-react
repository, and test it immediately using the example app.
Make sure you run first:
$ test/example_app/bin/yarn
$ test/example_app/bin/webpack
And optionally:
$ cd test/example_app/vendor/
$ yarn link "webpacker-react"
Finally, run the test suite:
$ rake test
If you change the javascript code, please ensure there are no style errors:
$ cd javascript/webpacker_react-npm-module/
$ yarn lint
Bug reports and pull requests are welcome on GitHub at https://github.com/renchap/webpacker-react. Please feel free to open issues about your needs and features you would like to be added.
This gem has been inspired by the awesome work on react-rails and react_on_rails. Many thanks to their authors!