Document React Hot Loader 3

[gaearon]

It features two modes (react-hot-loader/babel and react-hot-loader/webpack), doesn’t hide HMR API (you have to add module.hot.accept call yourself) and has a somewhat different API and setup process.

There’s info in gaearon/react-hot-boilerplate#61 and reduxjs/redux-devtools@64f58b7 but we should create good step-by-step docs and update the website too.

This will take a while because it’s not a priority for me. If you want to contribute, you are very welcome!
Obviously we can’t release 3.0 without any docs.

[gaearon]

To give some sense of perspective, if nobody contributes, the stable 3.0 might get out as late as June because I really don’t have the bandwidth to work on a good doc right now. It really is the biggest blocker to getting this version out!

[pablopaul]

@gaearon What kind of documentation is needed? Maybe you can give a rough documentation outline or so…

[gaearon]

We need to update this intro.

The new intro would be slightly longer because there is a bit more setup involved.
I would split it into several sections:

1. Enabling HMR
   • Create a development Webpack config separate from production one
   • Add HotModuleReplacementPlugin to development Webpack config
   • If you only render on the client, consider using WebpackDevServer
     • Easier to set up
     • Enable hot: true and add its entry points
   • If you use server rendering, consider using Express server + webpack-dev-middleware
     • More work but also more control
     • Show how to add webpack-dev-middleware and its entry point
2. Using HMR to replace the root component
   • Show how to add module.hot hook to re-render your root component
   • (This will not preserve state but is good enough for some cases!)
3. Adding React Hot Loader to preserve state
   • If you use Babel:
     • Add react-hot-loader/babel to plugins
   • If you don’t use Babel:
     • Add react-hot-loader/webpack to loaders
   • Add react-hot-loader/patch as the first entry point
   • Change your index.js to render <AppContainer> instead of your root component
   • That’s it!

[hedgerh]

I can help out with the docs. I've been reading up and gathering as much info as I can. I'm about to go through both the old and 3.0 source to try and figure out what's going on under the hood. I'll see if I can get the ball rolling on the Intro, as well.

[gaearon]

Thanks!

[gadicc]

Can I suggest we get started on Hackpad first? I think it will get us started quicker, and then we can use something like the Hackpad downloader to download as markdown to commit, moving forward.

I took an initial bash at https://hackpad.com/React-Hot-Loader-v3-CxSDMncWUnb.

[gaearon]

@gadicc @hedgerh Can I ask you to work it out between yourselves? I added you both as collaborators so you should be able to work on a single PR together without much hassle. (Up to you if you want to first take it somewhere else, but I would prefer reviewing on GitHub.) Just a reminder that the PR(s) would need to be sent against the next branch. Thanks!

[tsaiDavid]

@gaearon @gadicc @hedgerh

I've been following everyone's work and gathering info as well, and would be more than happy to help with documentation. Below, I took the work you all have started and simply rearranged the JSX component tags to make the layout a little more familiar for folks new to this.

We may want to clarify a couple of points that could prove to be confusing:

• RootContainer is simply an example of a named component, users should be able to swap it out for whatever they have already.
• The same thing applies to the ID of react-root - I can honestly see this point being a bit confusing as well since this requires configuration on the user's part. I'd be happy to help explain some of these bits.
• Finally, might we look into using something like GitBook as @gaearon had done with the Redux documentation? Setting up RHL3 would definitely take much longer than usual.

import 'react-hot-loader/patch';
import React from 'react';
import { render } from 'react-dom';
import { AppContainer } from 'react-hot-loader';
import RootContainer from './containers/rootContainer.js';

render((
  <AppContainer>
    <RootContainer />
  </AppContainer>
), document.getElementById('react-root'));

if (module.hot) {
  module.hot.accept('./containers/rootContainer.js', () => {
    const NextRootContainer = require('./containers/rootContainer.js');

    render((
      <AppContainer>
        <NextRootContainer />
      </AppContainer>
    ), document.getElementById('react-root'));
  })
}

[gadicc]

@gaearon, sure thing, thanks.

@hedgerh, sorry, I probably should have checked with you first on your progress but I just wanted to get the ball rolling. But now we can collaborate together :)

all, we'll track this in #257.

@tsaiDavid, help would be most welcome, thanks! Everything is on github now so see the issue above for more info.

In particular, I'll mention that I don't use or know how to use webpack, so help is very welcome in all webpack related content.