React is an amazing library for client-side user interface, and it has the added benefit of being able to be rendered on the server, which is crucial for SEO, SEM, and user experience. However, server-side rendering in practice is significantly more complicated than just calling `ReactDOMServer.renderToString` and piping out the result, especially if you want to make sure your site loads quickly in a mobile-first world. `react-server`: 1. Smoothes out the common problems you run into with React server-side rendering. 1. Encodes performance best practices into the framework, making it easy to build high performance websites by default. ## What we talk about when we talk about performance When we talk about performance in `react-server`, we're mostly talking about _perceived performance_. We believe that [WebPageTest](http://www.webpagetest.org/) is correct to focus on how much time it takes from the moment the user navigates the browser until the content above the fold is painted. There are other important perceived performance metrics (like time to first content painted, time to all content painted, and time to full interactivity), but in developing react-server, we have focused most on reducing time to above-the-fold paint. WebPageTest's [Speed Index](https://sites.google.com/a/webpagetest.org/docs/using-webpagetest/metrics/speed-index) is probably the best current measure of above-the-fold paint speed, as it takes into account how quickly the content is painted during load, not just the total time to full completion. In order to facilitate blazing perceived performance, `react-server` implements the following: * Parallelize backend queries * Bundle data for transfer to browser * Stream HTML to the browser * Wire up elements as they arrive * Render quickly, even when the backend is slow * Enforce page hygiene * Enable page-to-page transitions without code bloat * Look forward to HTTP/2 We'll examine each of these in turn and discuss why it makes it easier for web developers to write fast front ends, **by default**. ## Parallelize backend queries Traditional server-side rendering in frameworks like Ruby on Rails or Java Servlets has suffered from the fact that calls to the backend are usually synchronous. This means that every call to the backend to retrieve data happens in serial, meaning that page latency is at least the sum of the execution time of all backend requests. As a result, every feature added to a page slows down the time to first byte, and performance of the page degrades over time. In traditional LAMP, LAMJ, or RoR stacks, attempts to optimize this problem usually involve rewriting backend queries to retrieve more data at once, lowering the roundtrip cost to the backend, but this is time-consuming, error-prone, and often has unpredictable effects on performance, particularly for systems that use RDBMSes as their data store. Developers who care about performance have strong incentives to create bigger and more complicated backend queries to keep performance acceptable, which creates instability risk. In `react-server`, we advocate for performing as much of the backend data access as possible in parallel to speed up time to first byte from the server. Thus, if there are 10 backend data calls that each take 50ms, the server can theoretically finish access to the backend in 50ms rather than 500ms in a traditional, serial stack. Additionally, developers working with `react-server` and looking to speed up server performance have the right incentives: they are encouraged to break down big backend queries into smaller, more parallelizable queries. Smaller, more focused queries lower the risk of strain on the backend. Performance work can also have the added benefit of increasing stability. Parallel data access is mostly facilitated by node itself, which is built for highly asynchronous server applications. `react-server`, however, assumes that you will access the backend in a massively parallel way, and it facilitates building a user interface on top of parallel, asynchronous data access. ## Bundle data for transfer to browser One thing you quickly learn when you use React server-side rendering is that you have to "reconnect" React on the client side to the HTML markup you generated on the server side, and that's not always as easy as it seems. Ideally, reconnecting goes something like this: 1. On the server side, call `ReactDOMServer.renderToString` on a React element that you wish to render. This returns a string that represents a document fragment. The root of that document fragment will have an attribute (`data-react-checksum`) that is a simple checksum of the text of the entire fragment. 1. The server returns the document fragment to the browser wrapped in an HTML page. 1. In the browser, once the document has been loaded, the JavaScript code runs again, this time calling `ReactDOM.render` on the React element and also passing in the root of the pre-rendered HTML in the document. 1. React will construct a virtual DOM and run its checksum on that virtual DOM. If the checksum matches the `data-react-checksum` embedded in the pre-rendered HTML, React knows that the browser DOM is already in sync with its virtual DOM, and React doesn't have to do any browser DOM operations. If React finds that the checksums differ, however, it will blow away the existing DOM and replace it with the contents of the virtual DOM. This is a potentially expensive operation, and you want to avoid it if you can. The key lesson here is that when you send down pre-rendered markup from the server, you must also send down the exact data you used to construct that markup. If you don't, it's very likely that the virtual DOM you construct on the client side will end up looking different than the HTML you generated on the server side, and you will lose a major performance benefit of server-side rendering. In `react-server`, components on the server side load data via HTTP calls to the backend services of their choice, and `react-server` packages all those results into a **data bundle** that is sent down to the browser along with the HTML markup. The client-side bundle ensures that when the code runs again in the browser, it will have access to exactly the same data that the server side code did, and the client will therefore generate exactly the same DOM as the server did. But data bundle transfer doesn't just help with correctness when reconnecting client-side code to server-side markup; there's also a huge performance benefit. The data bundle transfer makes sure that data calls on the client return instantly, as they don't require an expensive network call to download data. From a developers perspective, this happens transparently and by default. ## Stream pre-rendered HTML Once we have parallel backend services and data bundle transfer, we're well on our way to developing a web experience that has good perceived performance. However, as our page gets longer and more fully featured, we run into another problem: our entire page, from header to footer, needs to be generated before we can send even the first byte to the browser. This means that the browser is waiting for all of our backend calls to finish and for `ReactDOMServer.renderToString` to return on the server before it even sees a body tag. We can easily lose hundreds of milliseconds or more during which the browser could be parsing and even displaying above-the-fold content. To solve this, `react-server` has the concept of a `RootElement`. Every page in a `react-server` app has multiple `RootElements`, and they stream down to the browser as soon as they are ready to render. That way, adding more content to a page at the bottom need not slow down above-the-fold paint. As a common example, imagine that we have a simple site where we want to show a user his or her profile. The page has three main sections: header, profile, and footer. While the profile section probably needs information from our backend, it's likely that the header doesn't need any at all. If we make the header its own `RootElement`, `react-server` will start streaming the header to the browser immediately, without waiting on any backend services at all, meaning that the user's browser can get a header back potentially within just a few milliseconds. Browsers are well equipped to render partial pages, and the user will be shown some content while the primary part of the page is still loading. ## Streaming client initialization Beyond simple streaming of the HTML content, `react-server` also initializes the `React` components in the browser _as they arrive_. You tell `react-server` how many of your elements are above the fold. Once the HTML for those elements has been sent `react-server` sends an inline `