Real-World Hydration and Rendering Patterns in Modern React Apps

Hey everyone, myself Ranjit Dandigam, I'm currently working as a software engineer at Naban. Today I'm going to talk about real-world hydration and rendering patterns in modern React apps. So this is not a generic React performance talk. The focus is very specific. What happens between server render HTML and streamed UI client hydration and the first interactions users can actually trust. So here is the main mental model for the talk. A React page does not become ready in one single step. First the server renders the HTML, then the browser receives the HTML shell and paints the first pixels. After that JavaScript loads. Then React hydrates the client components and attaches events. Some parts may stream later. Only after all important pieces are ready can the user trust the interaction. So when we say a page is fast, we need to ask fast at what stage? So was it faster to render, fast to paint, fast to hydrate or fast for the user to actually click and get a response? That is the difference I want to make clear today.

Here is the common production issue. The page looks good. The main content is visible. LCP may look healthy. There is no JavaScript error. But when the user clicks the save to button, there is no immediate feedback. So this is where users feel the page is slow. Even if our page load matrix looks OK, the important line here is painted does not mean ready. This is not always a component bug. Many times it is a timing problem between browser, JavaScript loading, hydration and the first real interaction. So a few years ago, most teams were asking adoption questions. Can we use server components? Is streaming ready? But now the question is different. So teams are already using these patterns. But now they ask why this stream is delayed. Why did hydration fail? Why does the page look ready but still feel slow? So the hard part in 2026 is not just learning the APIs, the hard part is operating this rendering model reliably in real applications.

So here we expand the same idea. So a route moves through the phases.

Request starts, server renders UI, HTML shell reaches the browser, browser paints. So then JavaScript loads, hydration attaches the events. After that streams resolve, finally the user can trust the interaction. So the risky gap is between browser paint and hydration. So during this gap, the UI may look ready, but events may not be attached yet. So that is when users may click a button and feel nothing happened. So when debugging, we should not only ask, did the page render? We should ask which phase is delayed? So here are the four states which actually explains. So in this case, rendered means React produced UI, but that does not always mean the user can see it. Whereas streamed means content arrives later, but that does not always mean it is hydrated. And hydrated means React attached to behavior, but it may not feel fast if the main thread is busy. And whereas interactive means the user can click, type and get a response quickly, but users judge the interactive state. So our architecture should make these states clear instead of mixing them together.

So here is the first pattern, which is server first boundaries. So the default should be server components. Then we add use client only where the browser is actually required. On this slide, you can see the cases, state, effects, browser APIs and client-only libraries. The goal is not to remove interactivity. The goal is to keep the interactive boundaries small. So most of the page can render on the server. Only small pieces like a button with a state or browser behavior need to hydrate on the client. So as you can see in the image on the left side, most of this is server on the box, but whereas only the save button is the client highland. So here is the pattern we would like to avoid, which is the component starts the use client. So the whole component is on the client side, then the data features happen inside the user side. So that means the browser must first load JavaScript, react must run, and only then the data request starts. Until the data returns, the user sees a skeleton. So the key problem is not the exact code. The key problem is the sequence, client render first, data fetched later. So where we can see, we have a use client and then we have this use effect in which we have this fetch API call. So the data fetching is tied to the client execution that creates a waterfall. So this is the better model where we have the trip header, trip summary, and hotel recommendations can be server render, and they do not need a browser state in this example.

Only the save trip button needs a client behavior because it has a click handler and a local state. So we keep the same user experience, but with a smaller hydration surface, same interactivity, less client work and easier debugging. If you look at the server render list first, then we can look at the save trip button on the left side screen, example screen. The server page owns the data on the server side, allowing the server to fetch trip data and produce useful HTML before the browser takes over. The save trip button remains, isolating client behavior to the part that truly needs it. The synchronization call with get upcoming trip and the save trip button with the trip ID exemplify this server-client data ownership.

A small client island, represented by the save trip button, demonstrates a clear separation between server and client responsibilities. This boundary ensures that client-side interaction is limited to specific elements requiring it, maintaining a clean architecture. The server-client boundary isn't just a notation but a crucial architectural decision impacting bundle size, hydration work, serialization, and debugging. Careful consideration of data sent to the client side is essential for efficient application performance. The streaming without waterfalls pattern addresses the issue of sequential waits, allowing independent resolution of components without blocking others. Fast sections no longer need to wait for slow ones, enhancing overall page responsiveness and usability.

The visual representation of the streaming model illustrates the sequential loading of elements like the shell, trip header, and summary in a non-blocking manner. By decoupling component loading, delays in one section do not impact the display of others. This approach ensures that slow-loading components do not hinder the rendering of faster elements, improving the user experience. Implementing boundaries and efficient streaming mechanisms in React applications can significantly enhance performance and maintain a smooth user interaction flow.

So a server-client boundary is not just a file annotation; it is an architectural decision. When data enters a client component, it impacts bundle size, hydration work, serialization, and debugging. Carefulness in choosing what is sent to the client side is essential. The rule of thumb is to treat data crossing into a client component as browser-visible. The streaming without waterfalls pattern addresses the sequential loading issue, allowing independent resolution of components without blocking others.

The streaming model visualizes sequential loading, ensuring that slow-loading components do not hinder faster elements. Fast sections no longer need to wait for slow ones, enhancing overall page responsiveness. The streaming approach decouples component loading to improve user experience. Suspense acts as a rendering control point, deciding what blocks the shell and what can arrive later.

The core of the streaming pattern involves awaiting shell dependencies, starting secondary work early, and letting suspense handle slower sections. By asynchronously loading rewards and hotel sections after the shell, the pattern enhances performance. This strategy ensures that the shell is not blocked by slow queries, prioritizing the rendering of essential elements. The approach optimizes React app rendering efficiency and user interaction flow.

So let's say in step 1, the shell appears, trip header and summary are already visible. And in step 2, rewards stream in after the shell. In step 3, hotels arrive later. So here the important point is suspense is not only loading a spinner, but suspense is a rendering control point. So we are deciding what blocks the shell, whereas what can arrive later.

So here is the code. So this is the heart of the streaming pattern. So in this code we can see we await for the trip because the shell needs it. Like we need it to render. Then we start reward section and hotels as the promises. We do not await them immediately. That means the work starts early, but it does not block the shell. So we just wait for the trips to load and then remaining things, the asynchronous reload.

So the pattern is simple. Await the shell dependency and then start the secondary work early. And let suspense handle the slower sections. As you can see, we are only waiting for the upcoming trip, but these rewards and then the hotel sections are going to load asynchronously. So if we start work early, we don't block everything. So now these promises are passed into suspense boundaries in this example. So each boundary has its own fallback. Rewards as a reward skeleton, hotels as a hotel skeleton. So this tells react, show the shell, now show fallback for this section and reveal the real content when the promise resolves. So the important part is not the skeleton. The important part is independent resolution.

So in this case, rewards and hotels do not need to block the rest of the page. So here suspense decides what can arrive later. So the third part is the hydration contract. So the server render HTML must match the first client render. So if the server produces one thing and the client produces something different during hydration, react has to reconcile a page that is already visible. So that can create confusing behavior.

So in this case, common causes are so typically the type of window, browser APIs, new date, math.runRandom, extensions, and CSS in JS trait. So here the key message is hydration mismatches are bugs. We should not ignore them. If you see on the server HTML and first client render in the diagram, so they must match. So here are the two common examples. So the first one is new date mismatch. So it is related to the date time, which can produce one value on the server, whereas another value on the browser.

So the second one, second common example is browser only branching. So let's say we have a type of window check, which can make the server render one output and the client render another output. So the APIs are not the problem. The problem is when the first client render does not match the server output. So in this case, the fix is simple. So we need to match first, then update after hydration. So if we match first and update after hydration, then we avoid those common issues.

So this is the safe time pattern, right? So the way we can make it safe is basically we start with the time as null. That gives us a stable first render, then inside use effect after hydration, we read the actual local time and update the UI. So the server and first client render can match. After that, the browser can show the real time. The fix is not never show time. The fix is to update it after hydration. So in this case, we will have a loading time until the time is available, and then we render the actual time.

So this is one of the biggest misunderstandings. Many of us think that type of window is not equal to undefined to avoid server crashes, but that part is fine. It can prevent code from running on the server, but it does not guarantee hydration safety. So here the server may render light theme, but the client may read local storage and render something else, maybe a dark theme. That means the first client render can be different from the server output. The type of window avoids a crash, but it does not automatically avoid a mismatch. So this is the better version. We start with a stable default value, which is light so that it is the same on both sides. Then after hydration, we read local storage inside the use effect.

So the first render can match, then the browser's specific value is applied safely. This is the same pattern again. We match first, then update after hydration. Here, the browser state belongs after hydration. Now let's switch from these slides to a local demo. This is a prebuilt Next.js app, no live coding, but I'll show you the dashboard we talked about so far. In the dashboard, there are three routes. What changes is the rendering behavior. We'll have three versions: client-side waterfall, server-first boundaries, and streaming with suspense. While I show the demo, we need to watch three things: when content appears, what happens in the network tab, and when the save button becomes usable.

And the version two is server first boundaries. And the version three is streaming with suspense. While I show the demo, we need to watch three things. When content appears, what happens in the network tab, and when the save button becomes usable. So here is the application, the demo application I have in my local. This is the Next.js app. I have all set up with the dashboard screen with three versions. Let me run the application. So yeah, it is going to run in localhost 3000, which is running here. So I'll go over. So this is a simple application, a dashboard screen with the three variations, three versions. So we'll go into the each version. But before that, let me open the network tab.

So first I will tap onto the client-side waterfall, where we actually make the API calls for each and every request. And then we wait for the client. We wait on the client side. So yeah, I'm clicking here. So as you see, so you'll see the page renders and then it waits for these rewards, hotels and then hotels, and there's this multiple things that are a known part. But yeah, so if you can see, if I refresh again, you'll see that it is a loading screen then actually client renders after everything fetches. So the same thing, you'll also see it in the logs, right? So it fetches everything and then the client is ready.

Now let me clear this, we'll go to the next version, which is two version second, which is server first boundaries. Let me clear this out. And then so we can see that server first boundaries actually waits for the page to get everything and then renders, renders the entire page at once. So that also you can see here. So we get the dashboard V2 and then we start the server render fetching all the data, which is trip data, rewards data, hotel recommendations, and then it renders the HTML. So this is what we were talking about in the second pattern, but whereas in the third pattern, we fetch what is needed to render the shell and then we fetch the remaining Cindy asynchronously.

So let me go through the streaming with suspense. So whereas you see these, the first trip loaded first, but after you, after that you see there's this hotels and then reward stream later, but it was fast. So let me update some timings from the delay so that you can actually see the streaming with suspense in effect. So now it refresh the page. Yeah, you see that this is loaded and then now slowly these report section and hotel section asynchronously render and also you'll see that same thing here. So you get a dashboard V3 and then starting server render fetching trip data, trip data ready, and then we have the streaming shell and then we'll fetch the remaining data. So this is what I was talking about in all these three patterns. I was talking about in all these three patterns.

So now let me switch back to the slides. So okay. So if you go back, so here is the production debugging checklist. So these issues, these issues usually fall into three buckets. First, hydration mismatch. So we need to check unstable values like date, math random, type of window, and HTML listing also reproduce without extension. And the second one, waterfalls, look for sequential await, start independent work early, check whether suspend boundaries are in the right place, watch network streaming. And the third one, it feels slow, but measure INP, mark hydration points, profile long task, keep contours lightweight. So the key idea is simple, debug the phase, not only the component. And this is the main architecture takeaway.

Rendering is no longer only a component level detail, it is a design decision. Before building a route, we should ask five questions. What can render on the server? What must hydrate on the client? What can stream later? What must be interactive immediately? So and what data is safe to cross the boundary? If we answer these questions early, the app becomes easier to reason about, easier to debug, and better for the users. So I'll close with the main idea. Visible is not the same as trustworthy, rendered is not the same as interactive, streamed is not the same as the hydrated. The goal is not to make every page fully server rendered or fully client rendered. The goal is to make every part of the page honest about when it renders, when it streams, and when it hydrates, and when users can actually trust it. So yeah, that's all about this talk. Thank you, thank you everyone.