People often ask why I moved off Medium. Doesn’t it have a better distribution than a personal blog? I’ll answer this question here. My reasons are simple:

1. Some of my Medium articles unexpectedly got behind a paywall*. I’m not sure what happened and whether that’s still the case. But I didn’t do it myself, and that caused a blow to my confidence in Medium as a platform. I respect their need to monetize, but it felt wrong when done retroactively.
   (* Folks from Medium reached out, and it appears that I confused one popup with another. In either case, I’m not the only one confused.)
2. My views on some topics have changed. I could continue blogging here but it feels a bit embarrassing to see my old writing just one scroll away. On the other hand, I don’t feel comfortable editing or deleting the old articles. I wanted to start from a clean slate, and this was my way to do it.
3. I want to dogfood React. Just like we heavily use React at Facebook, I’d like to use it more personally. My new blog is built with React. Before you bring out the “blogs don’t need React” pitchfork, consider that in my case using it improves the reader experience. Thanks to Gatsby, my blog works 100% without JavaScript, loads with a lightning speed, and the client-side JS enhances that experience with prefetching and seamless transitions.
4. I like to have full control over the experience. I like to have a corner of the internet where I can add silly details — such as rendering cups of coffee as a reading time approximation or offering to switch between dark and light themes. In the age of social media and homogeneous pages, it’s fun.
5. It’s open to the collaboration. My blog is open source. I started getting pull requests from community with fixes to RSS, code highlighting, SEO, and accessibility. What’s more, the React community added the support for translations and started writing them! Overreacted is almost fully translated to French, and one article has translations into 19 languages.

It feels good to have my own corner of the internet for the first time.

Even though Medium offers me a huge audience and a better distribution story, I don’t plan to write new articles on Medium.

See you on Overreacted.

This week, Sophie Alpert and I presented the “Hooks” proposal at React Conf, followed by a deep dive from Ryan Florence:

I strongly recommend to watch this opening keynote to see the problems we’re trying to solve with the Hooks proposal. However, even an hour is a big time investment, so I decided to share a few thoughts on Hooks below.

Note: Hooks are an experimental proposal to React. You don’t need to learn about them right now. Also, note that this post contains my personal opinions and doesn’t necessarily reflect the positions of the React team.

Why Hooks?

We know that components and top-down data flow help us organize a large UI into small, independent, reusable pieces. However, we often can’t break complex components down any further because the logic is stateful and can’t be extracted to a function or another component. Sometimes that’s what people mean when they say React doesn’t let them “separate concerns.”

These cases are very common and include animations, form handling, connecting to external data sources, and many other things we want to do from our components. When we try to solve these use cases with components alone, we usually end up with:

• Huge components that are hard to refactor and test.
• Duplicated logic between different components and lifecycle methods.
• Complex patterns like render props and higher-order components.

We think Hooks are our best shot at solving all of these problems. Hooks let us organize the logic inside a component into reusable isolated units:

Hooks apply the React philosophy (explicit data flow and composition) inside a component, rather than just between the components. That’s why I feel that Hooks are a natural fit for the React component model.

Unlike patterns like render props or higher-order components, Hooks don’t introduce unnecessary nesting into your component tree. They also don’t suffer from the drawbacks of mixins.

Even if you have a visceral first reaction (as I did at first!), I encourage you to give this proposal a fair try and play with it. I think you’ll like it.

Do Hooks Make React Bloated?

Before we look at Hooks in detail, you might be worried that we’re just adding more concepts to React with Hooks. That’s a fair criticism. I think that while there is definitely going to be a short-term cognitive cost to learning them, the end result will be the opposite.

If the React community embraces the Hooks proposal, it will reduce the number of concepts you need to juggle when writing React applications. Hooks let you always use functions instead of having to constantly switch between functions, classes, higher-order components, and render props.

In terms of the implementation size, the Hooks support increases React only by ~1.5kB (min+gzip). While this isn’t much, it’s also likely that adopting Hooks could reduce your bundle size because code using Hooks tends to minify better than equivalent code using classes. This example below is a bit extreme but it effectively demonstrates why (click to see the whole thread):

The Hooks proposal doesn’t include any breaking changes. Your existing code would keep on working even if you adopted Hooks in the newly written components. In fact, that’s exactly what we recommend — don’t do any big rewrites! It’s a good idea to wait with adopting Hooks in any critical code. Still, we’d appreciate if you could experiment with the 16.7 alpha to provide us with feedback on the Hooks proposal and report any bugs.

What Are Hooks, Exactly?

To understand Hooks, we need to take a step back and think about code reuse.

Today, there are a lot of ways to reuse logic in React apps. We can write simple functions and call them to calculate something. We can also write components (which themselves could be functions or classes). Components are more powerful, but they have to render some UI. This makes them inconvenient for sharing non-visual logic. This is how we end up with complex patterns like render props and higher-order components. Wouldn’t React be simpler if there was just one common way to reuse code instead of so many?

Functions seem to be a perfect mechanism for code reuse. Moving logic between functions takes the least amount of effort. However, functions can’t have local React state inside them. You can’t extract behavior like “watch window size and update the state” or “animate a value over time” from a class component without restructuring your code or introducing an abstraction like Observables. Both approaches hurt the simplicity that we like about React.

Hooks solve exactly that problem. Hooks let you use React features (like state) from a function — by doing a single function call. React provides a few built-in Hooks exposing the “building blocks” of React: state, lifecycle, and context.

Since Hooks are regular JavaScript functions, you can combine built-in Hooks provided by React into your own “custom Hooks”. This lets you turn complex problems into one-liners and share them across your application or with the React community:

Note that custom Hooks are not technically a React feature. The possibility of writing your own Hooks naturally follows from the way Hooks are designed.

Show Me Some Code!

Let’s say we want to subscribe a component to the current window width (for example, to display different content on a narrow viewport).

There are several ways you can write this kind of code today. They involve writing a class, setting up some lifecycle methods, or maybe even extracting a render prop or a higher-order component if you want to reuse it between components. But I think nothing quite beats this:

If you read this code, it does exactly what it says. We use the window width in our component, and React re-renders our component if it changes. And that’s the goal of Hooks — to make components truly declarative even if they contain state and side effects.

Let’s look at how we could implement this custom Hook. We’d use the React local state to keep the current window width, and use a side effect to set that state when the window resizes:

As you can see above, the built-in React Hooks like useState and useEffect serve as the basic building blocks. We can use them from our components directly, or we can combine them into custom Hooks like useWindowWidth. Using custom Hooks feels as idiomatic as using React’s built-in API.

You can learn more about built-in Hooks from this overview.

Hooks are fully encapsulated — each time you call a Hook, it gets isolated local state within the currently executing component. This doesn’t matter for this particular example (window width is the same for all components!), but it’s what makes Hooks so powerful. They’re not a way to share state — but a way to share stateful logic. We don’t want to break the top-down data flow!

Each Hook may contain some local state and side effects. You can pass data between multiple Hooks just like you normally do between functions. They can take arguments and return values because they are JavaScript functions.

Here’s an example of a React animation library experimenting with Hooks:

Note how in the demo source code, the staggering animation is implemented by passing values through several custom Hooks in the same render function.

(If you want to learn more about this example, check out this tutorial.)

While it’s not the primary purpose of Hooks, they also open the door for powerful interactive debugging tools:

The ability to pass data between Hooks make them a great fit for expressing animations, data subscriptions, form management, and other stateful abstractions. Unlike render props or higher-order components, Hooks don’t create a “false hierarchy” in your render tree. They’re more like a flat list of “memory cells” attached to a component. No extra layers.

So What About Classes?

Custom Hooks are, in our opinion, the most appealing part of the Hooks proposal. But in order for custom Hooks to work, React needs to provide functions with a way to declare state and side effects. And that’s exactly what built-in Hooks like useState and useEffect let us do. You can learn about them in the documentation.

It turns out that these built-in Hooks aren’t only useful for creating custom Hooks. They are also sufficient for defining components in general, as they provide us with all the necessary features like state. This is why we’d like Hooks to become the primary way to define React components in the future.

We have no plans to deprecate classes. At Facebook we have tens of thousands of class components and, like you, we have no intention of rewriting them. But if the React community embraces Hooks, it doesn’t make sense to have two different recommended ways to write components. Hooks can cover all use cases for classes while providing more flexibility in extracting, testing, and reusing code. This is why Hooks represent our vision for the future of React.

But Aren’t Hooks Magic?

You may have been surprised by the Rules of Hooks.

While it’s unusual that Hooks have to be called at the top level, you probably wouldn’t want to define state in a condition even if you could. For example, you can’t define state conditionally in a class either, and over four years of talking to React users I haven’t heard a complaint about this.

This design is crucial to enabling custom Hooks without introducing extra syntactic noise or other pitfalls. We recognize the initial unfamiliarity but we think this tradeoff is worth the features it enables. If you disagree, I encourage you to play with it in practice and see if that changes how you feel.

We’ve been using Hooks in production for a month to see whether engineers get confused by these rules. We found that in practice people get used to them in a matter of hours. Personally, I admit that these rules “felt wrong” to me at first too, but I quickly got over it. This experience mirrored my first impression with React. (Did you like React immediately? I didn’t until my second try.)

Note that there is no “magic” in the implementation of Hooks either. As Jamie points out, it looks pretty similar to this:

We keep a list of Hooks per component, and move to the next item in the list whenever a Hook is used. Thanks to the Rules of Hooks, their order is the same on every render, so we can provide the component with correct state for each call. Don’t forget that React doesn’t need to do anything special to know which component is rendering — React is what’s calling your component.

(This article by Rudi Yardley contains a nice visual explanation!)

Perhaps you’re wondering where React keeps the state for Hooks. The answer is it’s kept in the exact same place where React keeps state for classes. React has an internal update queue which is the source of truth for any state, no matter how you define your components.

Hooks don’t rely on Proxies or getters which can be common in modern JavaScript libraries. So arguably Hooks are less magic than some popular approaches to similar problems. I’d say Hooks are about as much magic as calling array.push and array.pop (for which the call order matters too!)

The design of Hooks isn’t tied to React. In fact, during the first few days after the proposal was published, different people came up with experimental implementations of the same Hooks API for Vue, Web Components, and even plain JavaScript functions.

Finally, if you’re a functional programming purist and feel uneasy about React relying on mutable state as an implementation detail, you might find it satisfactory that handling Hooks could be implemented in a pure way using algebraic effects (if JavaScript supported them). And of course React has always relied on mutable state internally — precisely so that you don’t have to.

Whether you were concerned from a more pragmatic or a dogmatic perspective (if you were at all), I hope that at least one of these justifications makes sense. If you’re curious, Sebastian (the author of the Hooks proposal) also responded to these and other concerns in this comment on the RFC. Most importantly, I think Hooks let us build components with less effort, and create better user experiences. And that’s why I’m personally excited about Hooks.

Spread Love, Not Hype

If Hooks still don’t seem compelling to you, I can totally understand it. I still hope that you’ll give them a try on a small pet project and see if that changes your opinion. Whether you haven’t experienced the problems Hooks solve, or if you have a different solution in mind, please let us know in the RFC!

If I did get you excited, or at least a little bit curious, that’s great! I have just one favor to ask. There are many folks who are learning React right now, and they will get confused if we hurry with writing tutorials and declaring best practices for a feature that has barely been out for a few days. There are some things about Hooks that aren’t quite clear yet even to us on the React team.

If you create any content about Hooks while they’re unstable, please mention prominently that they are an experimental proposal, and include a link to the official documentation. We’ll keep it up to date with any changes to the proposal. We’ve also spent quite a bit of effort to make it comprehensive, so many questions are already answered there.

When you talk to other people who aren’t as excited as you are, please be courteous. If you see a misconception, you can share extra information if the other person is open to it. But any change is scary, and as a community we should try our best to help people instead of alienating them. And if I (or anyone else on the React team) fail to follow this advice, please call us out!

Next Steps

Check out the documentation for Hooks proposal to learn more about it:

• Introducing Hooks (motivation)
• Hooks at a Glance (walkthrough)
• Building Your Own Hooks (that’s the fun part)
• Hooks FAQ (it’s likely your question is answered there!)

Hooks are still in an early stage, but we’re excited to hear feedback from all of you. You can direct it to the RFC, but we’ll also do our best to keep up with the conversations on Twitter.

Please let me know if something isn’t clear, and I’d be happy to chat about your concerns. Thank you for reading!

People blame Redux, React, functional programming, immutability, and many other things for their woes, and I understand them. It is natural to compare Redux to an approach that doesn’t require “boilerplate” code to update the state, and to conclude that Redux is just complicated. In a way it is, and by design so.

Redux offers a tradeoff. It asks you to:

• Describe application state as plain objects and arrays.
• Describe changes in the system as plain objects.
• Describe the logic for handling changes as pure functions.

None of these limitations are required to build an app, with or without React. In fact these are pretty strong constraints, and you should think carefully before adopting them even in parts of your app.

Do you have good reasons for doing so?

These limitations are appealing to me because they help build apps that:

• Persist state to a local storage and then boot up from it, out of the box.
• Pre-fill state on the server, send it to the client in HTML, and boot up from it, out of the box.
• Serialize user actions and attach them, together with a state snapshot, to automated bug reports, so that the product developers can replay them to reproduce the errors.
• Pass action objects over the network to implement collaborative environments without dramatic changes to how the code is written.
• Maintain an undo history or implement optimistic mutations without dramatic changes to how the code is written.
• Travel between the state history in development, and re-evaluate the current state from the action history when the code changes, a la TDD.
• Provide full inspection and control capabilities to the development tooling so that product developers can build custom tools for their apps.
• Provide alternative UIs while reusing most of the business logic.

If you’re working on an extensible terminal, a JavaScript debugger, or some kinds of webapps, it might be worth giving it a try, or at least considering some of its ideas (they are not new, by the way!)

However, if you’re just learning React, don’t make Redux your first choice.

Instead learn to think in React. Come back to Redux if you find a real need for it, or if you want to try something new. But approach it with caution, just like you do with any highly opinionated tool.

If you feel pressured to do things “the Redux way”, it may be a sign that you or your teammates are taking it too seriously. It’s just one of the tools in your toolbox, an experiment gone wild.

Finally, don’t forget that you can apply ideas from Redux without using Redux. For example, consider a React component with local state:

It is perfectly fine as it is. Seriously, it bears repeating.

Local state is fine.

The tradeoff that Redux offers is to add indirection to decouple “what happened” from “how things change”.

Is it always a good thing to do? No. It’s a tradeoff.

For example, we can extract a reducer from our component:

Notice how we just used Redux without running npm install. Wow!

Should you do this to your stateful components? Probably not. That is, not unless you have a plan to benefit from this additional indirection. Having a plan is, in the parlance of our times, the 🔑.

Redux library itself is only a set of helpers to “mount” reducers to a single global store object. You can use as little, or as much of Redux, as you like.

But if you trade something off, make sure you get something in return.

⚛

For personal questions, I maintain an AMA. If you want to know my favorite Pokémon, ask a question or read the answers!

If you have a programming question, read on.

“Hello, World” Questions

If you can’t get React to render a “hello, world” example or if your Redux counter doesn’t update when you press “+” and you’re stuck, you can message me directly on Twitter with that question.

I still encourage you to try asking on StackOverflow and Reactiflux Discord first. I often find that writing up the question makes it clear in my head, and the solution becomes obvious. But if you’re just making first steps and are really confused by something, I can definitely take a quick glance.

Please make sure to share what you’ve tried on GitHub, Gist, or, better yet, a fiddle before asking. This way we can make this a quick interaction instead of a back-and-forth. Otherwise it can be time consuming for both of us, especially due to different timezones.

Is your question more complex than a “hello, world”? Read on.

More Complex Questions

If your question is specific (e.g. something doesn’t work) and more complex than getting “Hello, world” running, please post it to StackOverflow first. I stopped answering such questions directly in messages because every time I get the same question I regret not having a link to my last answer.

If you send me a StackOverflow question in a message or in mentions, I will try to take a look at it and tell you if I can answer it. Which brings me to the next point.

How to Get Upvotes

The tricky part about asking good questions is to strike a balance between sharing too few and too many details. You need to phrase your question in a way that both explains your problem and sounds generic enough that other people find it useful. Browsing popular questions for any given tag can give you a good idea of what this looks like. It is a challenge! But if it is hard to ask a question, imagine what it’s like to answer it.

Nobody likes to invest 5 minutes into reading a question only to realize that it omits the part of the code that is crucial to understanding the problem. However, it is equally frustrating to read through 500 lines of code most of which are irrelevant to the issue.

It takes experience and care to ask good questions. You’ll get better at it. For now, it is enough that you make an effort. Here’s how I do it.

Isolating the Issue

Take the code that you have issues with, switch to another branch, and start removing parts that you suspect are irrelevant. Are you seeing the issue with a particular component? Render this component on the page alone. Is the issue still reproducible? Good. If not, bring the removed parts back one by one until you see which one causes the issue. Then isolate that part.

Next, remove all the irrelevant details from the buggy module itself. Keep removing the styling, markup, and business logic until the issue no longer reproduces. Eliminate as many dependencies as possible. Get to the absolute minimum code necessary to reproduce the issue.

Don’t forget to commit regularly! Otherwise you might remove too much and the issue might no longer reproduce. Make sure you always have a breadcrumb trail of what you have been doing.

Finally, try to recreate the issue in another environment. It’s handy to have a “base fiddle” using the same libraries as your project does. This way you can quickly create small independent snippets of code and paste the relevant parts of your project into them. There are some new services similar to jsfiddle but that provide access to npm modules. In particular, I heard good things about WebpackBin and ESNextbin. Check them out!

Most importantly, don’t give up too easily. There is a reason behind every issue. It can be a bug, a typo, or just a misunderstanding. Take comfort in the thought that this reason exists, and keep eliminating possible causes.

Experts often don’t know the problem any better than you. What they learned is not to trust themselves. They dig deeper and keep reducing the test case even if nothing obvious jumps at them for several hours. They know there is a problem somewhere, and finding it is a boring, mind-numbing but usually finite process.

If you’re debugging a problem late in the evening, drop it and sleep on it. Sleep deprivation makes it far too easy to miss typos and other simple mistakes.

You shouldn’t drive yourself to the point of despair either. If you’re stuck and you’ve exhausted your patience trying to isolate the problem, ask for help.

Linking to GitHub Projects

If you have no luck recreating the issue in a fiddle, it is fine to link to a GitHub project from a StackOverflow question. The chance that you will get a good reply is considerably slimmer but it’s worth trying as the last resort.

Here’s a few tips to make your chance of getting a good reply higher:

• Delete any unrelated files from the repository. Your project should build but if there is just one screen you’d like people to look at, delete all the others. You still need to trim down the reproducing case even if you share it on GutHub.
• Make sure all dependencies are specified in package.json. Imagine somebody wants to help you so much they clone your project, wait 15 minutes for npm install to finish, and then realize the project won’t start due to unspecified dependencies. To mitigate this, delete node_modules, run npm install yourself, and make sure the project starts swimmingly. If you forgot a dependency, add it to package.json and try again until it works.
• Make sure npm start will start your project. You can control what npm start does using the scripts field in package.json. It could be something as simple as “start”: “gulp”. The important part is that the person answering the question shouldn’t have to guess your bundler or task manager. All such tools should be dependencies in package.json.
• Don’t assume other people have Grunt/Gulp/Webpack/Browserify installed globally. You might have run npm install -g grunt at some point but many people don’t do this, or have different versions. Use npm scripts so that you don’t need to ask people to install and run global commands.
• Provide clear instructions to reproduce the issue in README. This is crucial. There is nothing like cloning a project, installing it, running it, opening it in the browser, and then having no idea how to reproduce the issue, or what the expected behavior is. Instead, you want to specify the exact sequence of steps (e.g. “npm start, open browser at this address, click on this button, I expected X to happen but Y happened instead”).

It is also a good etiquette to never delete the repository if you used it in a StackOverflow question.

Abstract Questions

Finally, there are a few questions that I can’t really give a good answer to.

“What is better, X or Y?”

Unless I used both of these solutions (highly unlikely), I’m not qualified to answer. Even if I used them both, the most I can share is a personal anecdote, not a verdict. My experience will be very specific to the project that I worked on. It is most likely outdated and might not apply to your project because we had different constraints and requirements.

Another problem is in the way this question is phrased. I always feel like the person asking it is trying to avoid a technical decision by delegating it to an “authority” (me in this case). I refuse to be an authority and I don’t want to be held responsible for other people’s choices. People also drastically overestimate how much I know. I’m clueless about a wide range of topics.

Instead, you can ask: “Have you worked with X or Y? If so, did you like either?” If I reply “No, but X looks cool” it doesn’t mean the project is good for you. It just means I liked its README.

Does this sound like useless advice? I think it is! The only way to find if something works for you is to create a small project with it, not to ask me about it.

“What are your thoughts on X?”

If I’ve never used X, I don’t have any thoughts on it besides “I kinda like it” or “I kinda dislike it”. Neither will be very useful to you, and knowing my opinion might even discourage you from going with a good choice. You have much more context about your problem than I do.

If I used X, I have more impressions than I can fit in a tweet. I don’t quite understand how to respond to this question on Twitter. I could write an essay in response but this would quickly become a full-time job.

If you’d like to engage me in a discussion about X, I’m happy to participate if I’ve used it. But let’s talk about something specific, not “my thoughts”. My thoughts are not interesting. Instead, I would like to hear about your experiences using it.

Finally, perhaps you built X. This is awesome! Help me and others understand what it is and why you built it. Explain not just what the API looks like, but how and why you are using it.

README is the best place to do this. Your tweets to me will get lost tomorrow. As much as I’d like to help, I probably don’t understand your use case well enough so my opinion won’t be very useful to you. Instead, seek out the people having the same problem, and ask their opinions.

Wrapping Up

Try to put yourself in the shoes of the person answering the question. You might discover that some questions are impossible to answer, or that you could have spent more effort crafting the question to get a better answer. Let’s value each others’ time and have more high quality conversations!

Note: React Hot Loader 3, released a month after I published this article, solves most of the problems described in this post. Give it a try!

React Transform is an experimental project I started after giving the Hot Reloading with Time Travel talk at React Europe.

My goal was to bring a live editing environment that preserves component state and handles errors gracefully to as many React users as possible.

By all reasonable metrics, React Transform has been a success. If anything, it proved the demand for a better development experience.

I would even say it has been way too popular for such an experimental and unpolished piece of software. This caused some pain for the people who felt pressured to adopt it and experienced problems with configuration.

I am sorry about this, as I had no time to focus on the experience of setting up the tool. There were, and still are, too many low level problems that need to be solved first before addressing the high level problems.

In fact I’ve come to realize that it is not a viable solution in the long term, and I plan to sunset React Transform in a few months in favor of a different project. You might think I have a habit of killing off my projects after they become successful. I assure you that this is not the case.

In this post, I will explain how I came to this conclusion, as well as describe my journey in understanding how hot reloading can be implemented, and the challenges I faced, in more detail than I did before. I hope this will be helpful to anyone who is curious where the magic comes from.

The underlying problem is that I’m inexperienced and I experiment in the open. If I make a mistake, it takes me some time to see that mistake for what it is, and even more time to come up with a solution.

React Transform is a mixed bag. It has some good ideas, but also has a bunch of fundamental problems. The good news is that I think these problems are soluble.

But first, let’s turn to the past.
It’s going to take quite a while so grab some snacks 😉

Trigger warning: accidental complexity.

Disclaimer

Today I will not discuss any tools that integrate with the browser engine. Personally, I am only interested in “userland” hot reloading technology. If you see this as an artificial limitation, you might be interested in Amok. It can do some incredible things like replacing functions inside closures thanks to its integration with the browser engine.

There are also some projects that use some of the hot reloading code I released under the hood but differ in their approaches to some questions. For example, LiveReactload is a separate project but it shares some parts of its implementation with React Transform. I’m not going to discuss such projects in this post as I only can tell you about my experience and the problems I have personally encountered.

I am also not going to spend time discussing hot reloading tools for compile-to-JS languages such as Figwheel and Elm Reactor. Their existence and simplicity is a big inspiration to me but at the moment I am primarily interested in the JavaScript tools that I can use in the existing React projects today.

JavaScript brings unique constraints that these tools don’t need to handle. Whether those constraints are enough to stop trying, or present an interesting challenge, can be described as a pure function of your convictions, determination, and time.

React Hot Loader

React Hot Loader was my first popular open source project and, to my knowledge, the first tool that allowed you to edit React component files without losing the state or unmounting the components.

How It Started

Like many other projects, React Hot Loader started with a question. I saw that Webpack Hot Module Replacement and React can be combined together in an interesting way, and I was excited.

You might have seen the video I used to introduce React Hot Loader:

The truth is it predates the real React Hot Loader. It was recorded at 6a.m. the day (or, rather, the night) I got the proof of concept working, and it relied on some horrible global variables I put inside the React source code just to record the video. Of course I didn’t tell that to anyone 😉.

I did not expect a lot of feedback but after Christopher Chedeau retweeted it my Twitter notifications went through the roof. I went from 12 to a 100 Twitter followers in a day so I knew people were as excited about it as I was.

I figured that I needed to turn this into a real project on a vacation, and that’s how React Hot Loader came to be a few weeks later.

First Attempt: Using HMR Directly

Before React Hot Loader, my first thought was that I could use Webpack HMR to replace the root component of my app and re-render it with React.

Note that HMR is not specific to React at all. James Long explains HMR well in this article. Basically it’s just a way for modules to say “When a new version of some module I import is available, run a callback in my app so I can do something with it”. This happens every time you save a file when HMR is enabled.

A vanilla HMR implementation of hot reloading a React app looks like this:

As long as you configure Webpack to enable HMR, the code above works fine and redraws your application when a hot reload occurs without refreshing the browser.

This implementation doesn’t use React Hot Loader, React Transform, or anything else—it’s just vanilla Webpack HMR API. It does not change the semantics of your React components. HMR is just a fancy way to poll the development server, inject <script> tags with the updated modules, and run a callback in your existing code.

Updates to nested components work because of how Webpack HMR API is designed. If a module does not specify how to handle updates to itself, the modules that imported it also get included in the hot update bundle, and the updates “bubble up” until they are all accepted by all the modules importing them. If some of the modules don’t end up being accepted, the hot update fails and a warning is printed. To “accept” a dependency, you just call module.hot.accept(‘./name’, callback) which Webpack parses at compile time.

Because we accept updates to App.js inside index.js, we also implicitly accept updates to anything imported from the App.js—such as other components.

For example, let’s say that I edit a Button.js component which is imported by UserProfile.js and NavBar.js. Let’s also say that those modules, in turn, are both imported by App.js.

Because index.js is the only module importing App.js and it includes a module.hot.accept(‘./App’, callback) handler, Webpack will generate an “update bundle” with all those files and then run the callback we supplied.

When we get an updated App.js, we just want to re-render the React app:

Problem solved?

In a way, yes.
But not really.

I told you it’s a long story! 🙅

Problem: DOM and Local State are Destroyed

When I say “next version of a module” I just mean that the module code is evaluated again in another <script> tag.

Because the App.js module gets re-evaluated, the class identity does not match the previous component class. So NextApp !== App even though technically they represent different “versions” of the same component.

As far as React is concerned, you’re trying to render a completely different type of component, so React will unmount the previous one. This makes sense: React can’t magically “change” the type of existing instances to a new class even if it wanted to!

This is why, with the approach described above, React destroys both the DOM and the local state of your components.

Possible Solution: Externalize the State

James Kyle recently pointed out that apps with a single state tree, such as Redux apps, don’t benefit as much from preserving the component local state. Often all you really need in such apps is to hold onto the external state tree.

In Redux apps, the complexity of preserving the local React component state might not be worth it because most of the state we’d like to keep in such apps is outside the components anyway.

Inspired by the conversation with him, I prepared this PR that removes React Transform from Redux examples in favor of vanilla HMR API.

James also suggested that you can use isolated-core for such cases. I haven’t looked at it yet, but I suggest you to check out isolated-core-demo if you are interested in this approach.

You can even have a decent development experience with full reloading when you have a single state tree. For example, you can save the Redux state to localStorage in development, read it before initializing the store so even Cmd+R doesn’t wipe it out, and call it a day.

Many apps can’t afford or don’t want to hold state in a single atom, and I think this is fine. I happen to think that we should not give up on preserving React local state just because some people don’t need it. 😉

However if you do use something like Redux, I strongly suggest you to consider using vanilla HMR API instead of React Hot Loader, React Transform, or other similar projects. It’s just so much simpler—at least, it is today.

Preserving the DOM and Local State

Now you see why naïvely replacing a React component with a re-evaluated version of it destroys the DOM and state of the existing instances.

I see two different ways to fix this:

1. Devise a way to detach React instances from DOM nodes and state, create the new instances of the new component types, and somehow “attach” them to the existing DOM and state recursively.
2. Alternatively, proxy component types so that the types that React sees stay the same, but the actual implementations change to refer to the new underlying component type on every hot update.

Please let me know if you are aware of any other solutions.

Failed Attempt: Rehydrating the Tree

The first approach is probably better in the long term but React currently provides no capabilities to (de)hydrate the state of React tree and replace the instances without destroying the DOM and running the lifecycle hooks. Even if we reached into the private React APIs to accomplish this, we would still face subtle problems with the first approach.

For example, React components often subscribe to Flux stores and other sideways data sources in componentDidMount. Even if we had a way to silently replace old instances with the new instances without destroying their DOM or state, the old instances would still keep their existing subscriptions, and the new instances would not be subscribed at all.

To subscribe the new instances, we would need to also fire lifecycle hooks on the them during the replacement operation. However then componentDidMount would run twice for the same DOM nodes which might break some assumptions that React components tend to make. In case of third-party components, you wouldn’t even be able to work around those assumptions because it is not your code!

Ultimately, the first approach probably be more feasible if React state subscriptions were declarative and independent of the lifecycle hooks, or if React did not rely so hard on classes and instances. Both may be the case in the future versions of React, but we’re not there yet.

Successful Attempt: Proxying Component Classes

The second approach is the one I use in React Hot Loader and React Transform. It is fairly invasive and changes semantics of your code but it gets the job done with today’s React, both in greenfield and legacy React applications. In most cases, it works great.

The idea is that every React component class gets wrapped into a “proxy”. In this case, I don’t mean an ES2015 Proxy although I’m definitely looking forward to using it instead of an ad-hoc approach I came up with.

Those proxies are just classes that act just like your classes but provide you the hooks to inject the new implementation of the class, at which point the existing instances start to act like the new version of the class. This way both React local state and DOM are preserved.

Problem in Retrospect: Lack of Tests

There are many non-trivial parts to creating a correct proxy, and React Hot Loader didn’t do it well because it didn’t have any tests. New versions of React used to break it all the time, and not writing a comprehensive test suite is the mistake I regret the most about React Hot Loader.

My latest work on proxying React components is available as a library called React Proxy. It is extensively tested, used inside React Transform but is low-level enough to be used separately. It only implements proxies for React components so it doesn’t depend on either Webpack or Babel. For example, I’m aware of people using it inside Electron apps as well as inside big projects with custom build systems.

Problem: Where to Wrap Components in Proxies?

Fun trivia: React Hot Loader is not a “loader” because it implements hot reloading. This is a common misconception. 😀

It is a “loader” because that’s how Webpack refers to what other bundlers call “transforms”. For example, json-loader transforms JSON files to JavaScript modules, and style-loader transforms CSS files into JavaScript code that injects them as stylesheets.

Similarly, React Hot Loader is also a compile time transform, and a rather dumb one. It wraps every React component that it finds in module.exports into a proxy, and exports the proxied components instead.

With this approach, when <App> renders <NavBar>, it really renders <NavBarProxy> (you wouldn’t know it though!) that calls NavBar#render() from its render() method and changes the internal reference to the newest version of NarBar whenever an updated NavBar.js module executes.

The proxies are stored globally by reasonably-unique IDs derived from the filename and displayName of the component classes. When an updated class is evaluated, the matching proxy is updated to “absorb” the new version of the class, and the components re-render without losing the local state or the DOM.

Looking for components in module.exports sounds like a reasonable approach at first. Developers usually keep every component in its own file anyway so naturally all components are exported. However, as time went by, and especially as new approaches became adopted by React community, I discovered some problems inherent to this approach:

• As higher order components became popular, people started to export the higher level component wrappers instead of the actual components they write. As a result, React Hot Loader didn’t “see” the inner components in module.exports and didn’t create proxies for them. Their DOM and local state would get destroyed on every change to the file. This is especially frustrating for higher order components that provide styling such as React JSS.
• React 0.14 introduced functional components which encourage micro-componentization inside a single file. Even if React Hot Loader inspected toString() of exported functions, looked for createElement() calls and assumed that these functions are React components, it still wouldn’t “see” the local components that aren’t exported. Those components would not become wrapped in proxies, and thus would cause the entire subtrees below them to lose both DOM and state. This jeopardizes the whole idea of preserving the state because it makes it extremely fragile.

Merely asking developers to export those “hidden” components isn’t enough because they are referenced inside the file! If we want to use the proxies, we have to somehow make sure that even references inside the file refer to those proxies instead of the actual components, which we obviously can’t do by overwriting module.exports.

At this point many people were saying: forget about it. Just use a global state solution and don’t attempt to preserve the local state.

Maybe I should have listened 😉.

Problem: Webpack Dependency

This was a big one. Webpack at the time was the only JavaScript bundler that implemented HMR. React Hot Loader proxy logic was not coupled to it but it wasn’t properly separated either. And of course React Hot Loader itself was a Webpack loader, first and foremost.

I worried: what if other bundlers don’t implement HMR? What if Webpack dies and gets replaced by something else? What about React Native which has been notoriously difficult to make friends with Webpack?

My intention was to at least make it possible for somebody else to use my work outside of Webpack—even if they had to also spend some time to hook that solution up to their bundler.

React Transform

About the time that I wrote The Death of React Hot Loader I was looking for ways to fix those problems.

Babel took the JavaScript world by storm, and I needed some kind of static analysis to locate and wrap the React components even if they are not exported directly. Babel seemed like a good fit for that.

Additionally, I was looking for a way to implement error handling. Hot reloading wasn’t very useful when every error thrown inside render() threw React into an invalid state, and I wanted to fix that.

Both wrapping component in a proxy and wrapping component’s render() in a try / catch sounded like “function that takes a component class and does something with it” to me.

So I thought: why not create a Babel plugin that locates React components in your codebase and wraps them in arbitrary customizable transforms?

Wouldn’t it be cool if other people created other developer-time transforms, for example, to overlay components with performance heatmaps?

This is how React Transform came to be.

First Approach: Modularity Overkill

I wasn’t sure which projects and ideas would still be relevant after a while so I decided to take an opposite approach to React Hot Loader. Instead of just one, I created five different projects under the “React Transform” umbrella:

• React Proxy implements low-level proxies for React components.
• React Transform HMR creates a proxy for a passed component and keeps a list of proxies on a global object so they are updated when the transform is called again for the same component.
• React Transform Catch Errors wraps the render() method in a try / catch and displays a configurable component instead if there is an error.
• Babel Plugin for React Transform does its best to find all React components in your codebase, extract information about them at compile time, and wrap them in the transforms that you chose (e.g. React Transform HMR).
• React Transform Boilerplate showed how these technologies work together.

Problem: Too Many Moving Parts

This approach became both a blessing, as it allowed easier experimentation, and a curse, as end users were increasingly confused about how those projects relate to each other. There were too many moving parts exposed to the user: “proxies”, “HMR”, “hot middleware”, “error catcher”, etc.

I made a mistake of hoping Babel 6 would come out soon with “presets” and I’d just be able to ship a preset with the preconfigured sane defaults.

However Babel 6 release came much later than I expected. (I’m not complaining because it was a terrifically complex release and Sebastian was burned out from the project, and did his very best in shipping it, for which I am very grateful.)

React Transform become popular way faster than I expected, and the complicated config I hoped would go away soon kept multiplying in the boilerplate projects, confusing new users. The fact that we included it in Redux examples made it even worse.

When Babel 6 came out, it turns out that the plugin needed a rewrite because I didn’t really know how to write Babel plugins and did it very sloppily. Luckily, James Kyle graciously rewrote it completely for v2.0 before ultimately deciding that the project is a bad idea and resigning from participating in it. Good thing he realized this after writing a v2.0! 😁

Solution: Sane Defaults

After the Babel 6 update and publishing an official preset, the modularity no longer was such a problem, and actually became useful because different environments (e.g. React Native) were able to take the parts they cared about. The lesson I learned is that any time you modularize something, you have to provide a good “default” interface for it. Those who are interested in the internal dependencies and customization will find them anyway.

Problem: Higher Order Components Strike Again

When you solve an issue, try not to introduce the opposite issue.

React Hot Loader could see anything you export from a file but couldn’t see the “local” components declared inside it. For example, React Hot Loader would find the exported component generated by useSheet() higher order component and update the styles on change, but it would not “see” the Counter itself, and for this reason its state would get reset when the file is saved:

React Transform “fixed” this by finding component declarations with static analysis, looking for classes that inherit from React.Component or are declared using React.createClass().

Guess what it’s missing? The exported components! In this example, React Transform would preserve the state of the Counter component and hot reload changes to its render() and handleClick() methods, but any changes to the styles would not get reflected because it doesn’t know that useSheet(styles)(Counter) happens to also return a React component that needs to be proxied.

Most commonly people discover this problem when they notice that their selectors and action creators in Redux are no longer hot reloaded. This is because React Transform does not realize that connect() returns a component, and there is no easy way to tell it.

Problem: Compile to JS Languages Don’t Babel

Naturally, using a Babel plugin excludes users of the compile-to-JS languages. Even if we told them to use Babel as part of their toolchain, we would still not be able to reliably find their class abstractions because of what they compile to. Sure, technically anything is possible but supporting this would probably be a nightmare because we would be relying on implementation details of third-party compilers.

Problem: Wrapping Components Statically Is Invasive

Finding classes that inherit from React.Component or created using React.createClass() is not too hard by itself. However it is potentially error prone, and you really don’t want to introduce false positives here.

With React 0.14, the task is even harder. Any function that returns a valid ReactElement is potentially a component. But you can’t be sure so you have to apply heuristics. For example, you can decide that any function in the top-level scope that is named in PascalCase, uses JSX and accepts no more than two arguments, is probably a React component. Are you going to get some false positives? Yea, probably.

Bad. Even worse, now you have to teach every “transform” to deal both with classes and functions. What if React introduces yet another way to declare components in v16? Would we have to rewrite all the transforms?

Finally, actually wrapping things statically is pretty complicated. You have to handle all the myriad ways of the way functions and classes can be exported in JavaScript, including default and named exports, function declarations, arrow functions, class declarations, class expressions, createClass() calls, and so on. In each case you need to find a way to bind a different value to the same variable or expression without screwing it up.

Introducing support for functional components has been the most requested feature in React Transform but I just don’t see it happening at this point because of the complexity it would impose on the project and its maintainers, and the potential for breakage due to edge cases.

Shall we give up at this point?

The Road Ahead

I still see both React Hot Loader and React Transform as successful projects despite their inherent flaws and limitations. I believe that great hot reloading experience can be achieved in React, and that we shouldn’t stop trying. In fact, it’s the first time in months that I felt optimistic about hot reloading React components.

React Native ships a hot reloading implementation based on React Transform very soon. It’s stable enough for now, but I also believe that we need a better and simpler solution looking forward.

Below I will describe this solution the way I see it.

Solution: Use Vanilla HMR If You Can

This is a straightforward one.

As James Kyle suggested, if you keep all your state in a single store like Redux, and don’t care too much about preserving the DOM on reloads, consider dropping React Transform and using vanilla HMR or something like isolated-core.

It will make your project simpler!

Solution: Drop Configurable Transforms

Configurable transforms were useful while React Native shipped with a fork of React and didn’t have an HMR implementation, but now it works with react package as is, and implements the necessary subset of HMR as well.

Browserify also now has an HMR plugin which, admittedly, is not bug-free, but I feel much more comfortable about using HMR as the “default” in the project. I think at this point it’s fair to ask other environments to polyfill it like React Native did.

React plans to ship an official instrumentation API that makes use cases like profiling or inspecting components much easier to implement in userland without resorting to wrapping them. In fact, doing this via DevTools API will be much more reliable, as the instrumentation code would be separated from the running application.

This is why I think the idea of highly configurable third-party transforms was a fundamentally flawed one, and we need to drop it. Let’s focus on hot reloading instead.

Solution: Use Error Boundaries

React v15 ships with an initial implementation of error boundaries which let components up the tree catch and display errors that occurred while rendering the components below the tree.

Effectively this means that wrapping components’ render() methods in try / catch blocks should no longer be necessary because you can implement your own <CatchErrors> component and put it at the top of your hierarchy and display errors like React Native does. We’ll probably ship such component together with the future hot reloading solution.

Solution: Proxy at the Call Site

I believe this to be the missing piece and the biggest mistake I made with React Transform. In fact Sebastian Markbåge told me in October that he wasn’t quite impressed with my Babel plugin but I didn’t understand his advice fully until I re-evaluated it a few days ago. The solution was right under my nose all this time.

Finding and wrapping React components in the source is hard to do, and is potentially destructive. This really might break your code.

On the other hand, tagging them is relatively safe. Imagine a Babel plugin that adds something like register(uniqueId, Component) at the end of the every module for anything that looks remotely like a component. For example, we can do this for every top-level function, class, and export:

What would register() do, then? The implementation I have in mind will check whether the passed value at least a function, and if it is, will create a React Proxy around it. It will not, however, replace your class or function! This is the important bit. The proxy will just sit in a global map, patiently waiting until you use… React.createElement().

If we got to React.createElement(), it’s the proof that whatever you pass there as a type really is a React component, no matter how it was declared.

As long as React Proxy supports all types of components (and it already supports both classes and functions), we should be fine. This is why we monkeypatch React.createElement() to refer to our internal map and to use the proxy instead of the passed type. It might look roughly like this:

With some changes to React Proxy necessary to get instanceof and similar checks right both inside and outside the component module, we should be able to get a reasonable approximation of the hot reloading behavior React Transform currently supports, and solve its many issues at the same time:

• There won’t be any false positives for components because wrapping occurs only for what is actually used as a component.
• We can “find” functions, classes, createClass() calls, and every export, and we don’t need to worry about writing complicated tree traversal logic to wrap different things correctly.
• Changing functional components will not reset the DOM or the state of the children trees.
• We can release React Hot Loader 2.0 that uses the same technique under the hood, but without the static analysis. It would only work for exported components, but this will be immediately useful to the compile-to-JS languages which are currently not supported by React Transform at all.
• The generated code would be easier to work with because we can move the generated lines at the end of the file instead of polluting the code like React Transform currently does.

I might be wrong here, and there still might be some problems that I missed, but overall this seems like a big step in the right direction to me, and all the groundwork like having a good proxy implementation or the code to find the createClass() calls is already done. We just need to remove the parts we don’t need, such as wrapping, and fix the edge cases.

If you plan to work on something like this, please let me know so I can help. If you don’t, well, I work at Facebook now, so maybe I can spend some time on this as well 😀.

Hopefully, with all the lessons learned, we’ll have better tooling for hot reloading in 2016. Once we get the low level implementation right, we can make the setup experience user-friendly. And someday we’ll clean up these hacks, and make React friendlier to hot reloading out of the box. But for now, being a step ahead of the accidental complexity is good enough to me.

A Little Update

Say hi to React Hot Loader 3.

⚛

If you’re new to React, you probably only worked with component classes and instances before. For example, you may declare a Button component by creating a class. When the program is running, you may have several instances of this component on screen, each with its own properties and local state. This is the traditional object oriented UI programming. Why introduce elements?

In this traditional UI model, it is up to you take care of creating and destroying child component instances. If a Form component wants to render a Button component, it needs to create its instance, and manually keep it up to date with any new information.

class Form extends TraditionalObjectOrientedView {
  render() {
    // Read some data passed to the view
    const { isSubmitted, buttonText } = this.attrs;

    if (!isSubmitted && !this.button) {
      // Form is not yet submitted. Create the button!
      this.button = new Button({
        children: buttonText,
        color: 'blue'
      });
      this.el.appendChild(this.button.el);
    }

    if (this.button) {
      // The button is visible. Update its text!
      this.button.attrs.children = buttonText;
      this.button.render();
    }

    if (isSubmitted && this.button) {
      // Form was submitted. Destroy the button!
      this.el.removeChild(this.button.el);
      this.button.destroy();
    }

    if (isSubmitted && !this.message) {
      // Form was submitted. Show the success message!
      this.message = new Message({ text: 'Success!' });
      this.el.appendChild(this.message.el);
    }
  }
}

This is pseudocode, but this is more or less what you end up with when you try to write composable UI that behaves consistently in an object oriented way with a framework like Backbone.

Each component has to keep references to its DOM node and to the instances of the children components, and create, update, and destroy them when the time is right. The lines of code grow as the square of the number of possible states of the component, and the parents have direct access to their children component instances, making it hard to decouple them in the future.

Now let’s talk about React.

In React, this is where the elements come to rescue. An element is a plain object describing a component instance or DOM node and its desired properties. It contains only information about the component type (for example, a Button), its properties (for example, its color), and any child elements inside it.

An element is not an actual instance. Rather, it is a way to tell React what you want to see on the screen. You can’t call any methods on the element. It’s just an immutable description object with two fields: type: (string | Component) and props: Object.*

When the element’s type is a string, an element represents a DOM node with that tag name, and props correspond to its attributes. This is what React will render. For example:

{
  type: 'button',
  props: {
    className: 'button button-blue',
    children: {
      type: 'b',
      children: 'OK!'
    }
  }
}

Such an element is just a way to represent this HTML as a plain object:

<button class='button button-blue'>
  <b>
    OK!
  </b>
</button>

Note how the elements can be nested. By convention, when we want to create an element tree, we specify one or more child elements as the children prop of their containing element.

What’s important is that both child and parent elements are just descriptions and not actual instances. They don’t refer to anything on the screen when you create them. You can create them and throw them away, and it won’t matter much.

React Elements are easy to traverse, don’t need to be parsed, and of course are much lighter than the actual DOM elements—they’re just objects!

However, the type of an element can also be a function or class corresponding to a React component:

{
  type: Button,
  props: {
    color: 'blue',
    children: 'OK!'
  }
}

This is the core idea of React.

An element describing a component is also an element, just like an element describing the DOM node. They can be nested and mixed with each other.

This feature lets you define a DangerButton component as a Button with a specific color property value without worrying about whether Button renders to a button, a div, or something else entirely.

const DangerButton = ({ children }) => ({
  type: Button,
  props: {
    color: 'red',
    children: children
  }
});

You can mix and match them later:

const DeleteAccount = () => ({
  type: 'div',
  props: {
    children: [{
      type: 'p',
      props: {
        children: 'Are you sure?'
      }
    }, {
      type: DangerButton,
      props: {
        children: 'Yep'
      }
    }, {
      type: Button,
      props: {
        color: 'blue',
        children: 'Cancel'
      }
   }]
});

Or, if you prefer JSX:

const DeleteAccount = () => (
  <div>
    <p>Are you sure?</p>
    <DangerButton>Yep</DangerButton>
    <Button color='blue'>Cancel</Button>
  </div>
);

This keeps components decoupled from each other, as they can express both is-a and has-a relationships exclusively through composition.

When React sees an element with a function or class type, it will know to ask that component what element it renders to with the given props.

When it sees

{
  type: Button,
  props: {
    color: 'blue',
    children: 'OK!'
  }
}

React will ask Button what it renders to, and it will get

{
  type: 'button',
  props: {
    className: 'button button-blue',
    children: {
      type: 'b',
      children: 'OK!'
    }
  }
}

React will repeat this process until it knows the underlying DOM tag elements for every component on the page.

React is like a child asking “what is Y” for every “X is Y” you explain to them until they figure out every little thing in the world.

Remember the Form example above? It can be written in React as follows*:

const Form = ({ isSubmitted, buttonText }) => {
  if (isSubmitted) {
    // Form submitted! Return a message element.
    return {
      type: Message,
      props: {
        text: 'Success!'
      }
    };
  }

  // Form still visible! Return a button element.
  return {
    type: Button,
    props: {
      children: buttonText,
      color: 'blue'
    }
  };
};

That’s it! For a React component, props are the input, and an element tree is the output.

The returned element tree can contain both elements describing DOM nodes, and elements describing other components. This lets you compose independent parts of UI without relying on their internal DOM structure.

We let React create, update, and destroy instances. We describe them with elements we return from the components, and React takes care of managing the instances.

In the code above, Form, Message, and Button are React components. They can either be written as functions, as above, or as classes descending from React.Component:

class Button extends React.Component {
  render() {
    const { children, color } = this.props;

    // Return an element describing a
    // <button><b>{children}</b></button>

    return {
      type: 'button',
      props: {
        className: 'button button-' + color,
        children: {
          type: 'b',
          props: {
            children: children
          }
        }
      }
    };
  }
}

When a component is defined as a class, it is a little more powerful than a functional component. It can store some local state and perform custom logic when the corresponding DOM node is created or destroyed. A functional component is less powerful but is simpler, and it acts like a class component with just a single render() method.

However, whether functions or classes, fundamentally they are all components to React. They take the props as their input, and return the elements as their output.

When you call

ReactDOM.render({
  type: Form,
  props: {
    isSubmitted: false,
    buttonText: 'OK!'
  }
}, document.getElementById('root'));

React will ask the Form component what element tree it returns, given those props. It will gradually “refine” its understanding of your component tree in terms of simpler primitives:

// React: You told me this...
{
  type: Form,
  props: {
    isSubmitted: false,
    buttonText: 'OK!'
  }
}

// React: ...And Form told me this...
{
  type: Button,
  props: {
    children: 'OK!',
    color: 'blue'
  }
}

// React: ...and Button told me this! I guess I'm done.
{
  type: 'button',
  props: {
    className: 'button button-blue',
    children: {
      type: 'b',
      props: {
        children: 'OK!'
      }
    }
  }
}

At the end of this process React knows the result DOM tree, and a renderer like ReactDOM or React Native applies the minimal set of changes necessary to update the actual DOM nodes.

This gradual refining process is also the reason React apps are easy to optimize. If some parts of your component tree become too large for React to visit efficiently, you can tell it to skip this “refining” and diffing certain parts of the tree if the relevant props have not changed. It is very fast to calculate whether the props have changed if they are immutable, so React and immutability work great together, and can provide great optimizations with the minimal effort.

You might have noticed that I have talked a lot about components and elements, and not so much about the instances. The truth is, instances have much less importance in React than in most object oriented UI frameworks.

Only components declared as classes have instances, and you never create them directly: React does that for you. While there are mechanisms for a parent component instance to access a child component instance, they are only used for imperative actions (such as setting focus on a field), and should generally be avoided.

React will take care of creating an instance for every class component, so that you can write components in an object oriented way with methods and local state, but other than that, instances are not very important in the React’s programming model, and are managed by React itself.

Recap

An element is a plain object describing what you want to appear on the screen in terms of the DOM nodes or other components. Elements can contain other elements in their props.

A component can be two things. It can be a class with a render() method that inherits from React.Component . Or it can be a function. In both cases, it takes props as an input, and returns an element tree as the output.

When a component receives some props as an input, it is because a parent component returned an element with its type and these props. This is why people say that the props flows one way in React: from parents to children.

An instance is what you refer to as this in the component class you write. It is useful for storing local state and reacting to the lifecycle events.

Functional components don’t have instances at all. Class components have instances, but you never need to create a component instance directly—React takes care of this.

Finally, to create elements, use React.createElement(), JSX, or an element factory helper. I discourage you from writing them as plain objects in the real code—just know that they are plain objects under the hood.

Further Reading

• Introducing React Elements
• Streamlining React Elements
• React (Virtual) DOM Terminology

Footnotes

* All React elements require an additional $$typeof: Symbol.for(‘react.element’) field on the object for the security reasons. I am omitting it in the examples above. Generally you should either use JSX or React.createElement() so don’t worry about it. I wanted to give you an idea about the raw API, so I wrote the objects inline, but to run this code, you need to add $$typeof to each of them.

• Classes obscure the prototypal inheritance at the core of JS.
• Classes encourage inheritance but you should prefer composition.
• Classes tend to lock you into the first bad design you came up with.

I think it’s great that the JavaScript community is paying attention to the problems caused by the use of classes and inheritance, but I’m worried that the beginners are confused as classes are both “bad” and were just added to the language. Even more confusingly, some libraries, notably React, use ES6 classes all over its documentation. Is React intentionally following “bad practices”?

I think we’re in a weird transitional period where the widespread usage of classes is a necessary evil because they are limiting. They are certainly better than learning a new ad-hoc class system that comes with every framework, each with its own way of multiple inheritance in form of mixins.

If you like functional programming, you might see how transitioning from proprietary class systems to the “stripped down” ES6 classes (no mixins, no autobinding, etc) moves us a step closer towards the functional solutions.

In the meantime, here is how to use classes and sleep at night:

• Resist making classes your public API. (Of course exporting React components is an exception as they aren’t used directly.) You can always hide your classes behind the factory functions. If you expose them, people will inherit from them in all sorts of ways that make zero sense to you, but that you may break in the future. Avoiding breaking people’s classes is hard because they might use the method names you want to use in the future versions, they might read your private state, they might put their own state onto your instances, and they might override your methods without calling super which may work for a while if they’re lucky but break later. That said, when there isn’t back-and-forth interaction between the base class and the user’s derived classes, such as in case of React components, exposing a base class may very well be a valid API choice.
• Don’t inherit more than once. Inheritance can be handy as a shortcut, and inheriting once is um-kay, but don’t go deeper. The problem with inheritance is that the descendants have too much access to the implementation details of every base class in the hierarchy, and vice versa. When the requirements change, refactoring a class hierarchy is so hard that it turns into a WTF sandwich with traces of outdated requirements. Instead of creating a class hierarchy, consider creating several factory functions. They may call each other in chain, tweaking the behavior of each other. You may also teach the “base” factory function to accept a “strategy” object modulating the behavior, and have the other factory functions provide it. Regardless of the approach you choose, the important part is to keep inputs and outputs explicit at every step. “You need to override a method” is not an explicit API and is hard to design well, but “you need to provide a function as an argument” is explicit and helps you think it through.
• Don’t make super calls from methods. If you override a method in a derived class, override it completely. Tracing a sequence super calls is like following a series of notes hidden around the world by a movie villain. It’s only fun when you watch someone else doing it. What if you really need to transform the result of the super method, or perform it before or after doing something else? See the previous point: turn your classes into the factory functions and keep the relationships between them very explicit. When your only tools are parameters and return values, it’s easier to discover the right balance of responsibilities. The intermediate functions can have different (and more fine-grained) interfaces than the “top-level” and “bottom-level” functions. Classes don’t easily provide such mechanisms because you can’t designate a method “for the use of base class only” or “for the use of derived class only”, but functional composition makes it natural.
• Don’t expect people to use your classes. Even if you choose to provide your classes as a public API, prefer duck typing when accepting inputs. Instead of instanceof checks, assert the existence of the methods you plan to use, and trust the user to do the right thing. This will make userland extensions and later tweaks easier, as well as eliminate the issues with iframes and different JavaScript execution contexts.
• Learn functional programming. It will help you not think in classes, so you won’t be compelled to use them even though you know their pitfalls.

So What About React Components?

I hope that the rules above show why this is a terrible idea:

import { Component } from 'react';

class BaseButton extends Component {
  componentDidMount() {
    console.log('hey');
  }

  render() {
    return <button>{this.getContent()}</button>;
  }
}

class RedButton extends BaseButton {
  componentDidMount() {
    super.componentDidMount();
    console.log('ho');
  }

  getContent() {
    return 'I am red';
  }

  render() {
    return (
      <div className='red'>
        {super.render()}
      </div>
    );
  }
}

However I say that the code below is just fine.

import { Component } from 'react';

class Button extends Component {
  componentDidMount() {
    console.log('hey');
  }

  render() {
    return (
      <div className={this.props.color}>
        <button>{this.props.children}</button>
      </div>
    );
  }
}

class RedButton extends Component {
  componentDidMount() {
    console.log('ho');
  }

  render() {
    return (
      <Button color='red'>
        I am red
      </Button>
    );
  }
}

Yes, we used the dreaded class keyword but we didn’t create a hierarchy, as we always extended Component. And you can write lint rules for that, if you wish so. There is no need to jump through the hoops just to avoid using the class keyword in the code above. It’s not a real issue.

When you want to supply a component with some additional functionality in a generic way, higher order components cover pretty much every use case I have encountered so far. Technically they are just higher order functions.

After discovering higher order components, I haven’t felt the need for either createClass()-style mixins, proposed-for-ES7 mixins, “stamp composition”, or any other composition solution. This is another argument in favor of just using class — because you don’t realistically need anything “more powerful”.

As of React 0.14 you can write the components as pure functions. This is totally worth doing. Any time you can write a function instead of a class, do.

However, when you need the lifecycle hooks or state, until React settles on some purely functional solution, I see no harm in using classes given that you don’t break the rules above. In fact it will be easier to migrate from ES6 classes to a purely functional approach than from anything else.

I am thus concerned about using “compositional solutions” that don’t directly harness React’s composition model, as in my view it’s a step back and conceptually is closer to mixins that don’t make sense in the functional paradigm.

So what are my recommendations for React components?

• You can use class in your JS if you don’t inherit twice and don’t use super.
• Prefer to write React components as pure functions when possible.
• Use ES6 classes for components if you need the state or lifecycle hooks.
• In this case, you may only extend React.Component directly.
• Give your feedback to the React team on the functional state proposals.

Sleep well!

In an earlier version of the slides, I had an “Inspiration” slide. I cut it, like I cut many other slides, to fit into the 30 minutes cap. If you were inspired by my talk, you probably already saw these three talks.

But if for some reason you missed either of them, I envy you.
They are the best.

• Turning the Database Inside Out
• Inventing on Principle
• Developing ClojureScript with Figwheel

There has been no shortage of great Flux implementations, such as Flummox, Alt, or Fluxible. Most of them are focused on making Flux easier to use with the server rendering and reducing the boilerplate. They also often provide convenience utilities like higher-order components and asynchronous action helpers. Still, under the hood, many of them are built on top of the original Flux Dispatcher.

Reducing the boilerplate of Flux is often a tradeoff. Some libraries have chosen to forfeit the great properties of Flux in order to be more succinct.

Say, if the actions aren’t plain objects flowing through a central dispatcher, it is much harder to record and replay actions for debugging. If the action type constants are not explicitly specified, and instead are generated from the method names, they might be more difficult to use together with the static analysis tools like Flow. That there is no single Flux library is a good thing, as the acceptable tradeoffs may vary for every team.

Now, unless you’re light years ahead of us and working on Om Next, Relay or something truly reactive, you might actually enjoy using Flux in your applications. If this is the case, you might want to know if there’s any real evolution happening in the Flux world.

Sure, figuring out how to make the isomorphic Flux easy was a step forward, but after that, the changes I have seen were either too cosmetic, or too drastic to call it Flux. The unidirectional data flow is important, but so is the relative ease of use of Flux, even for people who are not very keen on the functional programming yet. I think that if something requires you to understand cursors or observables, it might be great, but it’s not Flux. (I do like observables. But that’s not my point.)

So is Flux evolving? For the first time in many months, I think that the answer is yes. There are two API changes that I have noticed consistently in many new Flux implementations. These changes complement each other, and while they seem cosmetic, they also open up some exciting possibilities that weren’t available before. And they don’t even introduce any new concepts, such as cursors or observables!

I’m sure that Facebook considered these ideas, but decided to focus on the data flow and the ease of initial understanding. However I think that we’ve lived with this simple Flux long enough that we know its downsides, and it’s time to make it right.

The first change is to have the action creators return the dispatched action.
What looked like this:

export function addTodo(text) {
  AppDispatcher.dispatch({
    type: ActionTypes.ADD_TODO,
    text: text
  });
}

can look like this instead:

export function addTodo(text) {
  return {
    type: ActionTypes.ADD_TODO,
    text: text
  };
}

Of course, we can no longer call the action creators directly, but if you want to support server rendering, you’re likely to wrap them anyway (or have the library do it for you) so they’re bound to a specific dispatcher instance.

Why is it beneficial? It decouples actions from the dispatcher. The dispatcher becomes an implementation detail. It inverts the control, and we’ll see why inverting the control in Flux is important very soon.

How can async action creators work with this pattern? We could let the user return a function for dispatching multiple actions over time.

export function addTodo(text) {
  return dispatch => ({
    dispatch({
      type: ActionTypes.ADD_TODO,
      text: text
    });

    API.addTodo(text).then(
      () => dispatch({
        type: ActionTypes.ADD_TODO_SUCCESS,
        text: text
      }),
      () => dispatch({
        type: ActionTypes.ADD_TODO_FAILURE,
        text: text
      })
    );
  });
}

It’s easy to provide convenience helpers to make this pattern work with Promise or Observable without the boilerplate above.

This change is not so important by itself, but it works great in tandem with another change: making the Stores stateless. This sounds ridiculous, doesn’t it? Isn’t holding the state the point of Stores?

In my experience, it isn’t! Every Store I ever wrote was managing the state but there’s no reason for the Store to own the state. (Om users, please don’t roll your eyes now. If it’s obvious to you, you may as well go read LtU ;-)

What looked like this:

let _todos = [];

const TodoStore = Object.assign(new EventEmitter(), {
  getTodos() {
    return _todos;
  }
});

AppDispatcher.register(function (action) {
  switch (action.type) {
  case ActionTypes.ADD_TODO:
    _todos = _todos.concat([action.text]);
    TodoStore.emitChange();
    break;
  }
});

export default TodoStore;

can look like this instead:

const initialState = { todos: [] };

export default function TodoStore(state = initialState, action) {
  switch (action.type) {
  case ActionTypes.ADD_TODO:
    return { todos: state.todos.concat([action.text]) };
  default:
    return state;
}

That’s what your Store really is: a function telling the initial state and how the subsequent actions transform it. There is no reason for the Store to actually own that state. It might be held in a single big tree, for example, but it would be an implementation detail of the dispatcher. You don’t have to use the cursors. You can keep the “stores” and “subscriptions” mentality if that’s what you like, because it is easy to understand and feels natural to use.

What do these changes buy us? Turns out, quite a few things:

• Stores and actions are just pure functions. They are easily testable in isolation.
• Hot reloading. It’s easy to set up true hot reloading for stateless functions, and I’m working on an experimental project showing how both Flux Stores and Action Creators can be hot reloaded without disrupting the application development flow.
• Easy transactions. The dispatcher owns the state and has the power to revert the application to any previous state without the programmer implementing something like serialize() or deserialize(). This, combined with hot reloading, enables very powerful developer tools.
• No need for waitFor() because the dispatcher controls emitting changes and can emit them after all the Store callbacks have run.
• You can subscribe to the changes at the store level, but the dispatcher may also expose cursor-like functionality for the advanced users who need finer-grained updates.
• You’re specifying what, not how. Just like in React.

There are already quite a few work-in-progress experimental Flux frameworks exploring this (or similar) way of doing things. Here’s a few off the top of my head:

• microcosm
• fluce
• NuclearJS
• disto
• microflux
• fluctuations
• and the one I just started working on, redux

Keep this pattern in mind. You’ll see interesting things created with it.

Update

The ideas from this post have now materialized in babel-plugin-react-transform and its ecosystem. Check out react-transform-boilerplate!

React Hot Loader is my first JavaScript open-source project. It has enjoyed a tremendous response, and it has changed my professional life. True functional programmers don’t take it seriously, but comparing the wonder I felt the first time it worked to the mundane reality of hot reloading today, I know that it has made a difference in people’s minds, workflows and expectations.

New projects sharing the same vision, such as Amok by Casper Beyer and LiveReactload by Matti Lankinen, have appeared. Benoît Zugmeyer uses the core of React Hot Loader inside an atom-shell application. Just a few days ago Michael Johnston of the react-canvas fame managed to get React Hot Loader to work with React Native using react-native-webpack-server. I never expected any of this to happen, and I am thrilled and humbled to be in this company. Hell, I’m even going to ReactEurope!

The enthusiasm and the support I have received have been overwhelming. The flip side of this is that I’m always being painfully aware that React Hot Loader is a great hack. It’s not how hot reloading should work. What it shows is that it can work given today’s JavaScript applications’ constraints, despite the mutability, despite the state, and despite a myriad of other sins we commit in our apps.

In the long term, we should bring the better hot reloading solutions to the mainstream by spreading ideas, raising money for such projects, building tools, and documenting great, but obscure technologies that deserve to be widely adopted. I’ll be thrilled to deprecate React Hot Loader when I see a better way of achieving the same developer experience in JavaScript.

However, in the short term, there’s still a few things I want to fix in React Hot Loader before sending it off to gather dust in the legacy treasury of in-house IT departments.

Here’s how I think React Hot Loader 2 should be different.

• Instead of the weird module.makeHot opt-in API, export a decorator. Marking a class for hot reloading should be as easy as putting @hotify on it. In production, it would compile to a no-op, so there is no need for conditional statements in the user code. The project exporting @hotify decorator should be independent of Webpack. (Update: its alpha version is now available!) Re-evaluating the entire script with the new code with @hotify decorators in both scripts should have the same effect as hot reloading, except that such re-evaluation would usually cause unwanted side effects. (Which is where Webpack’s Hot Module Replacement fits nicely, providing granular bubbling module updates and module cache for the unchanged modules.)
• Hotifying only module exports doesn’t cut it anymore. It doesn’t work with higher-order components that wrap the real classes. Instead, we need to go back to finding React components in the source code. It was tricky and unreliable when React Hot Loader operated on the source file string, but what if it was a Babel plugin instead? (Update: its alpha version is now available too!) For example, a plugin could slap @hotify onto any class with render method. It could also be configured to process module exports and even locate components using a custom project-wide heuristic. That Babel plugin could even generate hot reloading code for Webpack (and potentially, other build systems). This way we may be able to converge with LiveReactload at some point.
• What about the CoffeeScript and other compile-to-JS users? Nothing prevents them from keeping using the old Webpack loader! It would just need to be changed to hotify exports using the same @hotify decorator that the Babel plugin would use.

We already have a separate “hot loader core” project, but its API is not usable directly and, frankly, hard to understand. In the coming months, I will work on making it more developer-friendly.

As the time passes, React Hot Loader will gradually disappear. Instead, I hope that an ecosystem will appear, each part ready to be replaced by something better when the time is right.

Follow Dan Abramov on Twitter

⚛