Tweak React components in real time ⚛️⚡️
- Editing functional components preserves state
- Works great with higher order components
- Requires little configuration
- Automatically disabled in production
- Works with or without Babel (you can remove
rlyeh/lib/babel-plugin
from.babelrc
and instead addrlyeh/lib/webpack
toloaders
) - Watch Dan Abramov's talk on Hot Reloading with Time Travel.
npm install rlyeh
- Add
rlyeh/lib/babel
to your.babelrc
:
// .babelrc
{
"plugins": ["rlyeh/lib/babel"]
}
-
Add
rlyeh/lib/patch
at the top of the entry section (except polyfills) of your Webpack config:
// webpack.config.js
module.exports = {
entry: [
'babel-polyfill',
'rlyeh/lib/patch',
'./main.js'
]
}
- Wrap your application into
<AppContainer>
, all children of<AppContainer>
will be reloaded when a change occurs:
// main.js
import React from 'react'
import ReactDOM from 'react-dom'
import { AppContainer } from 'rlyeh'
import App from './containers/App'
const render = Component => {
ReactDOM.render(
<AppContainer>
<Component />
</AppContainer>,
document.getElementById('root'),
)
}
render(App)
// Webpack Hot Module Replacement API
if (module.hot) {
module.hot.accept('./containers/App', () => { render(App) })
}
Note: To make this work, you'll need to opt out of Babel transpiling ES2015 modules by changing the Babel ES2015 preset to be
["es2015", { "modules": false }]
You may not use Babel in your project, Rlyeh provides a Webpack loader with limited support. If you want to use it, you can add it in your Webpack config. If you use Babel, you don't need to add this loader.
// webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.jsx?$/,
use: ['rlyeh/lib/webpack']
}
]
}
}
Migrating from create-react-app
-
Run
npm run eject
-
Install Rlyeh (
npm install --save-dev rlyeh
) -
In
config/webpack.config.dev.js
:- Add
'rlyeh/lib/patch'
to entry array (anywhere beforepaths.appIndexJs
). It should now look like (excluding comments):
entry: [ 'rlyeh/lib/patch', require.resolve('react-dev-utils/webpackHotDevClient'), require.resolve('./polyfills'), paths.appIndexJs ]
- Add
'rlyeh/lib/babel'
to Babel loader configuration. The loader should now look like:
{ test: /\.(js|jsx)$/, include: paths.appSrc, loader: 'babel', query: { cacheDirectory: findCacheDir({ name: 'react-scripts' }), plugins: [ 'rlyeh/lib/babel' ] } }
- Add
-
Add
AppContainer
tosrc/index.js
(see step 4 of Getting Started).
When using TypeScript, Babel is not required, so your config should look like (demo):
{
test: /\.tsx?$/,
loaders: ['rlyeh/lib/webpack', 'ts-loader'] // (or awesome-typescript-loader)
}
If you use devtool: 'source-map'
(or its equivalent), source maps will be emitted to hide hot reloading code.
Source maps slow down your project. Use devtool: 'eval'
for best build performance.
Hot reloading code is just one line in the beginning and one line in the end of each module so you might not need source maps at all.
React Native supports hot reloading natively as of version 0.22.
The previously used Redbox
for Rlyeh has known limitations due to sourcemaps and it's no longer a default catcher. Errors are great to clearly see rendering issues, and avoiding an uncaught error from breaking your app. But there are some advantages to a thrown error in the console too, like filename resolution via sourcemaps, and click-to-open. To get the Redbox
back, and have the best of both worlds, modify your app entry point as follows:
import Redbox from 'redbox-react';
const CustomErrorReporter = ({ error }) => <Redbox error={ error } />;
CustomErrorReporter.propTypes = {
error: React.PropTypes.instanceOf(Error).isRequired
};
render((
<AppContainer errorReporter={ CustomErrorReporter }>
<AppRoot />
</AppContainer>
), document.getElementById('react-root'));
You'll also need to npm install --save-dev redbox-react
.
Provided by collaborators:
- react-hot-boilerplate (Bare minimum)
- react-hot-loader-minimal-boilerplate* (Bare minimum)
Provided by community:
- react-kit (webpack v2, redux, react-router v4, code splitting, jest, saga, reselect)
- hapi-react-hot-loader-example (ES2015, Universal (SSR), React Hot Loader 3, React Router 4, Redux, Redux Saga, Redux Form, Async Component Code Splitting, Hapi, Webpack 3)
- typescript-hapi-react-hot-loader-example (TypeScript, Universal (SSR), React Hot Loader 3, React Router 4, Redux, Redux Saga, Redux Form, Async Component Code Splitting, Hapi, Webpack 3)
- react-redux-styled-hot-universal (SSR, Universal Webpack, Redux, React-router, Webpack 2, Babel, Styled Components and more...)
- webpack-react-redux (redux, react-router, hmr)
- react-lego (universal, react-router, other optional techs)
- react-static-boilerplate (static site generator; React, PostCSS, Webpack, BrowserSync)
- react-cool-starter (universal, redux, react-router, webpack 2, Babel, PostCSS, and more...)
- react-redux-saga-boilerplate (react-router, redux, saga, webpack 2, jest w/ coverage, enzyme)
- react-universal-boiler (webpack 2, universal, react-router, redux, happypack)
- apollo-fullstack-starter-kit (universal, apollo, graphql, react, react-router, knex)
- react-universally (universal, react, react router, express, seo, full stack webpack 2, babel)
- meatier (webpack 2 + hmr, universal, redux, graphql, react, react-router-redux, ssr)
- react-hot-ts (React, Webpack, TypeScript)
- react-boilerplate-app (react (duh), router, webpack with dev server, babel, hot reloading)
- react-native-web (react-native-web, webpack with dev server, hot reloading and flow soon...)
- react-starter-kit (webpack 2 + htr + react + redux + router + babel + sass)
- redux-react-starter (webpack 2 + redux + react-redux 5 + react-router 4 + styled-component ...)
- react-redux-universal-boilerplate (redux, react-router, universal, koa, webpack 2, babel, PostCSS, sass or cssnext, hot reloading, ...)
- ARc (React, Jest, Storybook and other optional feature branches)
- webpack-react-redux-starter (webpack 2, browsersync, babel, eslint, mocha, enzyme, jsdom, production config, detailed readme, and more...)
- trowel (universal/ssr, redux, react-router 4, webpack 2, postcss)
- react-navigation-web (react-navigation in web + redux, hot reloading!)
- react-universal-hot-loader-starter-kit (universal express app with webpack 2, react-router 4, redux and react-hot-loader 3)
- bare-minimum-react-hot-rr4-redux (Bare minimum webpack 2, react-router 4, redux)
- react-webpack2-boilerplate (Minimal react-router-3, react-redux, redux-saga on webpack2 with full hot reloading include reducers, sagas and react-components)
- react-webpack-boilerplate (Boilerplate for ReactJS project with Webpack2 hot code reloading!)
- react-boilerplatinum (Webpack2, Babel, React, Dev Server, PostCSS, SASS, PurifyCSS, HMR, Standard, Offline, BrowserSync)
- ts-react-boilerplate (react, typescript 2, webpack 2 + hot-reload, karma + jasmine + coverage, sourcemaps)
- react-boilerplate (Dead simple boilerplate for ReactJS. Webpack 2, Redux. Hot Loader. Router)
- molecule (Production ready boilerplate targeting web & electron, using webpack 2, redux, react-hot-loader, immutable.js, react-router and more)
- universal-js-hmr-ssr-react-redux (Universal JS, Webpack 2, React Router 4, Server Side Rendering, Code Splitting, Redux, Express)
- Rlyeh can't replace any Component, only registered ones.
- when using webpack loader - only module exports are registered.
- when using babel plugin - only top level variables are registered.
- when Rlyeh can't replace Component, an error message will be displayed.
If you want to use Webpack code splitting via require.ensure
, you'll need to add an additional module.hot.accept
callback within the require.ensure
block, like this:
require.ensure([], (require) => {
if (module.hot) {
module.hot.accept('../components/App', () => {
loadComponent(require('../components/App').default);
})
}
loadComponent(require('../components/App').default);
});
Note that if you're using React Router (pre-4.0), this will only work with getChildRoutes
, but not getComponent
, since getComponent
's callback will only load a component once.
Also, if you're using the Webpack 2 beta, you can use System.import
without extra module.hot.accept
calls, although there are still a few issues with it.
Because Rlyeh creates proxied versions of your components, comparing reference types of elements won't work:
const element = <Component />;
console.log(element.type === Component); // false
One workaround is to create an element (that will have the type
of the proxied component):
const ComponentType = (<Component />).type;
const element = <Component />;
console.log(element.type === ComponentType); // true
You can also set a property on the component class:
const Widget = () => <div>hi</div>;
Widget.isWidgetType = true;
console.log(<Widget />.type.isWidgetType); // true
Rlyeh will only try to reload the original component reference, so if you reassign it to another variable like this:
let App = () => (<div>hello</div>);
App = connect()(App);
export default App;
Rlyeh won't reload it. Instead, you'll need to define it once:
const App = () => (<div>hello</div>);
export default connect()(App);
Components that are decorated (using something like @autobind
) currently do not retain state when being hot-reloaded. (see #279)
If it doesn't work, in 99% cases it's a configuration issue. A missing option, a wrong path or port. Webpack is very strict about configuration, and the best way to find out what's wrong is to compare your project to an already working setup, such as React Hot Boilerplate, bit by bit.
If something doesn't work, in 99% cases it's an issue with your code - Component doesn't got registered, due to HOC or Decorator around it, which making it invisible to Babel plugin, or Webpack loader.
We're also gathering Troubleshooting Recipes so send a PR if you have a lesson to share!
MIT