How Razzle Works

TL;DR: 2 configs, 2 ports, 2 webpack instances, both watching and hot reloading the same filesystem, in parallel during development and a little webpack.output.publicPath magic.

In development mode (razzle start), Razzle bundles both your client and server code using two different webpack instances running with Hot Module Replacement in parallel. While your server is bundled and run on whatever port you specify in src/index.js (3000 is the default), the client bundle (i.e. entry point at src/client.js) is served via webpack-dev-server on a different port (3001 by default) with its publicPath explicitly set to localhost:3001 (and not / like many other setups do). Then the server's html template just points to the absolute url of the client JS: localhost:3001/static/js/client.js. Since both webpack instances watch the same files, whenever you make edits, they hot reload at exactly the same time. Best of all, because they use the same code, the same webpack loaders, and the same babel transformations, you never run into a React checksum mismatch error.