Hot-reloading in 2018: updated and unabridged

using React + RequireJS (and Node.js, of course)

Alex Mills
Sep 6, 2015 · 22 min read


> a how-to guide and why AMD and RequireJS are currently best for the job.

Special update: You can basically consider SystemJS and AMD/RequireJS to have equivalent hot-reloading capabilities. The general opinion expressed in this article is that these two front-end module loaders are superior to Webpack and Browserify from the standpoint of implementing reliable and robust hot-reloading functionality. Throughout the article, you can basically substitute “RequireJS” with “SystemJS” and the meaning will remain the same.


page-refresh = live-reload

hot-reloading = hot-module-replacement = hot-swapping

The current ‘state-of-the-art’ for developer productivity on the front-end is something called ‘live-reload’. What this means is that the page/app will refresh when certain files are modified in the codebase. Live-reload, as I will argue, is a very suboptimal workflow, when compared with a true hot-reloading system. In fact, I would argue strongly, that hot-reloading is the #1 missing feature in the vast majority of web developers workflows, even in 2018. I will explain why that is, throughout this article.

Some questions for the reader

  1. Why aren’t Angular5 apps, created with AngularCLI, pre-configured for hot-module-replacement?

This is something to think about. You will find out why as you read on.


In the very beginning of my journey to survey hot-reloading in the world of web development, I was inspired by Dan Abramov’s excellent talks about hot reloading front-end static assets with Webpack and React — it inspired me to investigate whether it could be done with RequireJS. In short I succeeded in this, and below there is some code showing you how to create hot-reloading using a Node.js Express server application with RequireJS as the front-end module loader. There is no module or library to install — this article simply gives you a methodology/recipe to follow on your own. What it allows you to do is to take full advantage of the standard RequireJS feature of asynchronous loading of modules, to enable hot-reloading of front-end static assets, including React components, of course. Most developers do not really know what hot-reloading is and many developers will literally die without having used hot-reloading on the front-end — thinking with 100% confidence that a page-refresh is about as good as it gets. This is sad, please don’t let it happen to you.

Beyond the code in this article, I created an example project that showcases how to do hot-reloading with the same setup as this article (at some point I’d like to make this into a Yeoman generator):

We can do dynamic loading of JavaScript modules for both the server and client, but I would like to focus on the client because this is a more useful utility for developers. (If you want some info on hot-reloading files on a Node.js Express server, see here:

Here are the big 4 advantages of hot-reloading:

  1. No page refresh means console logging is intact. A page refresh will destroy the logging statements in your web browser console, effectively starting an entirely new JS runtime; hot-reloading does not require a browser refresh at all — which of course means your logging statements are naturally preserved which makes general development and debugging a lot easier! This is also one reason why SPAs are better than server-rendered apps — we don’t experience as many page-refreshes which means it’s easier to debug the front-end.* This makes hot-reloading much better than “live-reload.”
  • BONUS — Hot-reloading will encourage good coding patterns — most importantly it will continue to encourage developers to keep all state out of the DOM and into JavaScript. For example, if there is state in the DOM, and you hot reload some HTML (or a React component), that state will get lost, but your state should not have been there anyway! Hot reloading will also encourage you to keep state in parent components instead of child components, etc.

*If you do have to refresh the page, and you cannot currently implement hot-reloading, I recommend sending your console logging from the browser to a log file on the developer’s filesystem and tailing that log file, which means you can reference logs from previous runtime sessions. I have never tried this but sounds like fun to implement lol.

RequireJS has an ace-in-the-hole when it comes to hot-reloading on the front-end. You will be surprised as to how little code is needed to get this to work with RequireJS, compared to how complicated it is to both accomplish and understand with Browserify or Webpack. Here’s the thing people: RequireJS does hot-loading out-of-the-box by design, in production, and has been doing so for a very long time — this is because it has asynchronous loading or ‘lazy-loading’ as a primary feature. You may have noticed there’s a small trend of creating multiple bundles for single-page-applications so that not all your code loads on page-load. RequireJS got it right the first time by building a model for front-end web applications which load assets asynchronously and on-demand.

So there are two primary reasons that RequireJS is the best module system for implementing hot-reloading:

  1. RequireJS is an asynchronous module system and is designed from the ground up for lazy-loading/hot-loading of modules.

So RequireJS does hot-loading, but how do we do hot RE-loading? Well, we use RequireJS’s native ability to delete the cache for a module, and then we re-require the module from the filesystem. You will learn much more by reading on, and may be surprised by how straightforward this is.


hot-reloading — the same as hot-module-replacement or hot-swapping; in this case it’s for web front-end static assets; I’d like to draw one distinction between ‘hot-reloading’ and ‘hot-code-push’ — HCP is when you push live updates to your users’ devices. So basically, HCP and live updates are for production releases and hot-reloading is intended primarily for development, even though they each share similar results. Some people also draw a distinction between code that is hot-swapped and code that is eval’d. In this case, the former is the case, but I am not sure if that distinction is a useful one.

RequireJS — asynchronous JavaScript module loader designed primarily for the AMD module format but can also work with CommonJS; dependency management is tightly controlled by both code and configuration

Browserify — a JavaScript module loader designed to get CommonJS modules into the browser; in both development and production, by default Browserify concatenates JS modules into one file per page load

Webpack — a module bundler that is agnostic about module format — works with AMD, CommonJS and ES6; exceptionally good at deploying different optimized files for “multiple entry points” to a single-page-application. If you want to get started with Webpack, Pete Hunt’s how-to is probably as good a place to start as any. I personally find the “multiple entry points” description a bit misleading. By “multiple entry points” we are still talking about a SPA (single-page-application), it’s just that we aren’t anywhere near finished loading static assets upon the first page load — so IMO there’s only one “entry-point”, which is page load, but there are other points in the application where new static assets are incorporated into the runtime. *Edit 12/12/2016, ok this original part is not 100% correct. With Webpack we can build SPAs or server-rendered apps, Webpack is agnostic about that. So we can have true multiple entry points with server-rendered/multi-page apps, or pseudo-mutltiple entry points with SPAs + code-splitting.*

hr4R — an example project I created to demonstrate hot-reloading with RequireJS

All due respect to Browserify — I don’t see any reason to use Browserify now that Webpack is on the scene, because Browserify focuses on CommonJS and is also focused on creating one deployment file. After about 800KBs or so, most developers find the file to be too big to parse and execute, especially on mobile devices. If you wish to work with Browserify, there is this module which you can try out to hot-reload React components-, but this is not the same as hot-reloading.

In his talks, Dan Abramov emphasizes the importance of improving your workflow before anything else. DX (Developer Experience) is a thing now. Hot reloading front-end static assets is a big part of improving DX and is intended to save you serious amounts of time that you would otherwise spend in frustration, endlessly iterating through front-end design permutations — waiting for builds to complete, and clicking refresh or waiting for refresh and re-navigating to re-capture the same state you had before you made the change — (perhaps only to find a runtime error with your JSX!).

Hot reloading exists so that you can hot swap the minimum amount of code to see the change, so that changes can be made to your program without affecting your program’s state — it is supposed to allow you the developer to completely avoid the need to refresh the page and re-navigate to where you were in your app to recapture state to see how the changes that you just made took hold —merely saying it with words takes too much time.

It might take 2–10 seconds to wait for a rebuild, click refresh (or wait for auto-refresh) and worst of all, re-navigate to where you were. Or in that time you could have started reading Quora, Medium, Twitter or Facebook and completely lost focus. You must stay in the flow state! Do not interrupt the flow!

Hot-reloading has nothing to do with Nodemon, it is not Forever, it is not PM2 or Node-Supervisor, it is more powerful than that for front-end development, simply because hot-reloading “eschews the refresh” — all you need to do is save a file and it is transported to the browser so that you can see changes in near real-time.

As Dan says in his videos, hot-reload functionality is supposed to make life better for devs and take some of the frustration out of front-end development — to save us from long front-end build times and endlessly clicking through our apps in development cycles.

My belief is that Browserify and Webpack (the two latest and greatest front-end modules loaders) have put us further away from the dream of universally understood hot reloading for front-end development, not closer!

as I will describe, the RequireJS / AMD spec was practically made for the job. I will give you enough information in this article to figure out how to hot reload JS, HTML and CSS on your own, even if you don’t use the exact tools and modules I use here, the concept will resonate. Also, there is the example project, aforementioned, which you can check out at your leisure.

This article and the code laid forth herein is for anyone who:

  • uses RequireJS (with React, Backbone, Angular, or whatever) and wants to improve their workflow

I hereby present the solution to a big chunk of your front-end problems: HR4R — hot reloading for RequireJS. As implied, the benefits of hot reloading with HR4R are:

  • you can see JSX transpilation errors as you write the code — the module is being loaded and run in the browser in real time which allows you to see errors long before you otherwise would’s old logo was really ugly, now it’s not so bad.

As for Webpack’s own React Hot Loader, Dan Abramov seems to have given up his project (and I honestly don’t really know why):

It seems that Dan has been working against, instead of working with, the tools at hand. As far as I can tell, Dan is working against Webpack and he is working against Babel. Why not use a more straightforward module loader and not bother with transpiling ES6 with Babel? Hot reloading with Webpack seems difficult and is a “hack” according to Dan — (although I take his words with a grain of salt — it doesn’t seem like a total hack to me — especially considering that Webpack was designed for hot reloading before Dan arrived). Nevertheless, from my perspective, trying to get hot reloading to work with Webpack (or Browserify — good luck with that) seems like an uphill battle, even if Webpack was designed to handle it — there is so much more code involved in getting it work than the code I will show you to get it working with RequireJS. If I had to pick between hot reloading and ES6, I would choose the former.

Introducing HR4R

So I’d like to introduce a system I created to hot reload JS, CSS and HTML templates into the browser using RequireJS, Node.js, Gulp.js file-system watchers and I have tested it with React and Backbone. It is not a module to install, it is merely a methodology to follow. I am not sure if it would work with Angular, Ember, Durandal/Aurelia, but chances are that it could with some tweaking (although many frameworks have their own module system — so you’d more likely want to use Angular and Ember to reload the modules instead of RequireJS — even though I have heard it is best practice to use an external module loader / build system). I will go over the higher level procedures regarding how hr4R works, and then we can dig into some code. I created one module (requirejs-metagen on NPM) that you can use to require entire directories of files, but otherwise it’s up to you to implement this. This is a good thing. You can see conceptually how this can be done, and copy some of the code, but you get to code it yourself so that you actually understand it.

Finally: How to do hot reloading with front-end JavaScript

You need:

  • a filesystem watcher process (gulp.js in this case)

Here are the high-level steps we take (details to follow):

(1) in your gulpfile.js at the root of your project, we add a server listening on port 3002 - your gulpfile is now your dev server! congrats

(2) in your gulpfile.js, we use to watch for filesystem changes in particular directories.

(3) upon a filesystem change in a particular directory, the server running in your gulpfile.js will send a message to the browser with a string, representing the path of the file that changed; your front-end code needs to be able to handle that message, and (re)require the file that has changed.

(4) somewhere in your front-end code, preferably in it’s own module, add a connection to localhost:3002 (you can do a check for what environment you are in — and only make the socket connection when you are in development — assuming you don’t want hot reloading in production.) And you shouldn’t have to worry about CORS when it comes to making socket connections to multiple servers, if you already have a connection to some server running somewhere.

(5) Configure all your views to refresh references to any templates, child views, or CSS that it would need to render. No need to mark files with metadata — a view is “@hotifiable” if it is able to refresh the references. To configure your views to update references involves using this syntax in RequireJS:

also described here:

anyway, synchronous require calls in RequireJS / AMD look like this:

So, once your application is loaded in the browser, nothing happens. There is no polling, nothing of the sort! Hot reloading starts with you hitting ctrl+s or ctrl+z on your keyboard when editing a file that is being watched by Gulp (I use Windows at home and a Macbook Pro at work, and I remapped my keys on my Mac to match Windows — I still don’t understand how most people hit the command key on a Mac — it’s in the wrong place). The change event is fired (if there is actually a change to the file) and now you have the filepath of the file that changed on the front-end, because pushed it there, and it’s up to you to do something with it.

Here’s the code for parts (1), (2) and (3) with comments:

Here is the code for part (4)

Here is where the magic happens — require.undef() is the call that deletes the cache and forces RequireJS to re-require modules from the filesystem:

Here is an example of nested React components that get updated. If you have a view showing a top level React component and you update the file for the nested component in your IDE, it will all get hot-reloaded. The key is (1) to ensure that the child views are loaded before rendering the parent view and (2) re-evaluating the reference to the child-views in the render function, with the synchronous require call. This is all made very easy by RequireJS:

So here are the subtle tricks to getting hot reloading to work with RequireJS:

  • require.undef() as per:

One thing left to say — if we want hot reloading to be easier in the future, we may need an asynchronous/on-demand module loading system for ES6, a la RequireJS. I don’t believe Browserify or Webpack make hot-reloading as easy as it should be, although I am going to have to give Webpack a fair shot.

If you have any questions don’t hesitate to leave comments or email me at Thanks for reading this. Spread the word. Hot reloading should be available to all front-end developers, especially those who do design work.

If you enjoyed this tutorial - it would be helpful if you could click the recommend button and share it with other developers.

“Eschew the refresh”, my friends :)

:: More info if you want it ::

If you wish for more information or background, I edited everything below this out of the article because it was getting to be too much, but here’s more info:

Are there pre-existing solutions?

Despite the perceived benefits, hot reloading front-end code is not universally available and support for it appears spotty, as if it were always a secondary goal for front-end frameworks. It was actually fairly hard for me to find good information on this whole thing. Frameworks like Angular, Ember were probably not designed for hot reloading out of the box (please correct me if I am wrong), and hot reloading for libraries such as Backbone and React was nowhere near in scope for those projects. The only semi-official support for hot reloading for any major web framework that I know of is Meteor — — Meteor added hot reloading support as early as 2012, but as far as I can tell it is deprecated, or at least depreciated, as supporting hot reloading was too difficult due to Meteor’s isomorphism (think: with an isomorphic system where code between server and client is highly coupled — how would the system easily know if the code you changed only affected the client? If it possibly affected the server you’d have to restart the server — see the problem? The problem is that Meteor server restarts can taken up to 30 seconds — they are working on it!). Here’s a direct quote:

“So, hot-pushes aren’t getting enough love in meteor imo. Meteor guys are trying to make things fast in their build process, but it isn’t fast enough yet.”

Furthermore, hot reloading is also not universal because it pretty much requires universal browser support of websockets, something we didn’t really have even (3?) years ago, thanks HTML5 and!

Some problems with other systems and hot reloading:

  • using Angular “source maps stop working when using Webpack’s hot code reloading, but it’s a price I’m willing to pay.”

Those sound like real issues with vanilla Angular1.x and Webpack. So what if we used RequireJS instead of Webpack?

It turns out, RequireJS and the AMD module format were made for hot reloading. Think about what the AMD spec (specification) is all about. Asynchronous-Module-Definition. Asynchronous. As implied, AMD is a spec for JavaScript modules whereby modules and their dependencies are loaded asynchronously* — this means we can load modules on demand at anytime in our app, in development or production (in production we typically bundle most of our static assets together with the r.js optimizer — *but* you can still dynamically require a nominal file(s) with RequireJS in production, and this is standard practice). AMD is primarily used on the front-end whereas the CommonJS format was originally designed for Node.js.

The mechanism to do hot reloading described in this article should apply for most module loaders, but it will be easier to execute if you have a module system that was designed from the ground up to load new modules on the fly.

The only two complaints I ever hear regarding RequireJS:

(1) too much ceremony with the define statements

my answer: I like the define statements — as they remind me that I am working on the front-end instead of the back-end. JavaScript everywhere is great, but isomorphic JavaScript is overrated unless you are working with Meteor (or server-side rendering with React) and it’s nice to have a gentle reminder of where you are in your app with the RequireJS syntax.

(2) AMD makes it difficult to share code with the server.

my answer: As I said, isomorphic JS is overrated. Now I do realize we are firmly in server-side-rendering-React-land territory. I haven’t bought into that yet. (Why are we doing tons of CPU intensive work on a Node.js server if we could delegate that to hundreds or thousands of clients, again?) If you want some isomorphism, it’s extremely easy to convert CommonJS to AMD. (The CommonJS → AMD conversion has been automated for you already.) However it’s more work to convert AMD to CommonJS, probably two minutes of manual time per module on average. But as many have pointed out, how often do we really need to share whole modules between the server and client — not often — having JS on both the client and server is useful enough, we don’t need it to be exactly isomorphic.

Even though we might need to run a build with RequireJS to transpile JSX, Sass/Less, or whatnot, if we need to load just one new file, we can do that without the need to rebuild and redeploy the entire project, which can take at least a couple seconds with Browserify or Webpack. Even with incremental builds and watchify, it can still take several seconds to build Browserify and Webpack — with RequireJS, your code will be hot loaded in much less than a second — I actually include a small delay (setTimeout) so you can swivel your head and see the confirmation of a successful reload.

In development, RequireJS generally advocates for a 1:1 relationship between module and file, and does not want or need a build system. Whereas Browserify and Webpack will need (incremental) builds to get new modules into the air. This is the web goddamnit: I thought we were dynamic and left the slow compilation and building to C++ and Java? In development, this may mean more HTTP requests, but in production you will bundle your RequireJS app. If you design your router in your front-end application to only load views on demand, I promise you that there will only be about 5–10 HTTP requests per view change which is nothing really. In production, if you designed your RequireJS application optimally, each view change will require a maximum of 1 HTTP request to retrieve new HTML/CSS/JS, because it has been bundled for production.

Plus no source maps — in development mode the AMD code in your browser is the same as it is on your filesystem. It couldn’t be simpler. I can just see in my mind’s eye all those devs out there waiting for their Webpack or Browserify build to complete so they can hit the refresh button :) This is a chance at an upgrade, my friends.

I personally find AMD quite beautiful. AMD is one of three primary module specs for JS, along with CommonJS which was developed for Node.js and ES6 which is supposed to be a first universal module system for JavaScript. It’s hard to say when ES6 will truly replace CommonJS and AMD, but I am in no rush. It seems that with Angular 1.x and Meteor, and whatever else, being dependent on ES5, that ES6 will only gradually be incorporated in codebases.

As for when to use RequireJS, Webpack or Browserify. It seems that Webpack’s primary competitive advantage is its ability to create separate bundles or entry points for your front-end app. But RequireJS can do that too with its bundle feature. From what I have gathered through reading and my experience, for websites (as opposed to mobile) it seems that 1MB is about as big of a (un-gzipped and un-minified ) JS file you want to send for any request. (Pete Hunt from Facebook/Instagram has a mediocre talk on this subject on Youtube). So you might want to separate your project into multiple entry points (like Instagram does), only including the JS necessary for each major entry point. However for most SPAs, you can just send JavaScript, CSS, and HTML once, on the first request, that is, if it’s not already cached on the client’s browser.

We are seeing two ‘new’ trends in web development, with React, Webpack, etc:

  • server-side rendering (again)

RequireJS has no clear advantage in being used for server-side rendering (TMK), however if you think carefully about the second trend, you might realize that we are coming full-circle on this one, just like we are with the first. It used to be (not too long ago) anathema to modern web development to require JS, HTML or CSS on the fly once your app was loaded. However, Webpack is basically saying — for big web applications or for mobile or both — we need that — we can’t bundle everything in one big .js file for the first page load. So as you can see, RequireJS’s original intentions of asynchronous loading of files throughout the lifecycle of an web application was not inherently flawed, at all. A full-page-reload is bad, that’s agreed on, but asynchronously loading new files on demand seems like a good thing.

*It turns out that in production, RequireJS modules are primarily loaded synchronously, they only use the asynchronous syntax, because that’s what you used to run the code in development. Furthermore, in development, as long as a given module is known to already be loaded, you can use synchronous syntax to load a module synchronously, and as you may have noticed, this is one of the secret sauces that allows us to do hot reloading with RequireJS and React (or Backbone) together. RequireJS is super cool and major props to James Burke for making something that was very well designed. I intend to continue using RequireJS as I don’t really see any downsides to the format. When Angular 2.0 rolls around I might start messing with ES6 and TypeScript, but again, I am in no rush.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade