Is TanStack Starts Deferred Hydration Revolutionary?

TanStack Start has a new performance feature called deferred hydration. So you know what hydration is, you're probably gonna know that this is a feature you're going to want to take a look at. Let me give you a real quick demo to show what I'm talking about. Right here we have a regular hydration SSR page. This carousel up at the top here is the thing that we're really interested in, and this little chit over here telling us when it's hydrated or not is very important in this demo. Now this version of the carousel is eagerly hydrated, which is the standard for React components. Now let's take a look at the TanStack Hydrate version You can see we've got this carousel in the state of dehydrated, waiting for intent. And in this case, as I mouse over it, that shows that we have intent to interact with it, and it's only at that point is that carousel hydrated. Now, normally this kind of product carousel would actually be below this main callout here. I'm putting it at the top because it's really the thing that we wanna interact with in this demo. But normally it would be down below this product, and that's why this hydration thing is interesting. If it's down below the fold, and what the user usually connects with is the product itself and not this carousel, then to defer the hydration of this carousel makes a lot of sense. But at this point you might be like, "Well, what is hydration again? And why does it matter?" So that's what I'm gonna do first. I'm gonna teach you about hydration and then I'm gonna show you these new hydration controls. Let's get right into it. Here's all the steps that a React SSR app has to go through between getting the web request in the first place to get the page, all the way to when it's interactive and the user can press something like add to cart, which is really important. On the server side, it all starts with a route request, and then we load the data for that route, and then we render that route. And the output of that is the HTML, the CSS, the JavaScript, and then the serialized route data. The browser does what it does, which is to parse and display that HTML as well as load and execute the JS. The framework then loads all that route data and then re-executes all of that page code on the client to rebuild a full new DOM, and that's called hydration. So it's taking the data and then it's essentially hydrating a new state on the client. So why is it doing that? Well, it's important to understand the difference between source code and state. What was sent to the client was the source code as well as the initial route data. But nothing else, no other state associated with the app was serialized. So we have to essentially rebuild that state and that DOM tree on the fly. So you're getting source code, but not state. Which is kind of interesting because as an aside, with React server components, you actually get state but not source code. So that's something to think about. But back into hydration. Once we've created that new DOM, we then compare it against the DOM that we have, and if all is well, then awesome, we are now interactive As you can see, the big performance bottleneck in this case is this hydration pass. So the less that we can do in hydration, the better. Now from a product perspective, we know that certain parts of the page, like add to cart, are mission critical, so they need to be interactive as soon as possible. They need that eager hydration. But there's some parts, like our carousel, that we can defer the hydration to a different time. So what we've had in React, and now we've got some more syntactic sugar in TanStack Start to make this even easier, is two different ways to specify when we want that hydration to happen. The first is selective hydration. That's what the React team calls it, and that's where you're essentially just postponing the hydration till immediately after interactive. And then there's deferred hydration, which is what TanStack Start has brought to the party, and that's the ability to defer that hydration potentially indefinitely, potentially forever, or until some condition is met that you think is important for hydration. The critical piece here is understanding when does a component need to be hydrated? Does it need to be interactive right away? If so, then it should stay with eager hydration. If not, then it can be deferred till when the customer actually wants to interact with it. Over in the source code that's associated with this video, there's then a link in the description right down below over on GitHub. There is a src/hydration-variants folder, and in there is the RegularHydration component, and this is basically just the React component. So we have our HydrationChip in there that tells us whether we're hydrated, and because we aren't doing anything extraordinary, we're just going to be eagerly hydrated. Now when it comes to TanStack, we can bring in this new Hydrate component from TanStack React Start, and we can also bring in some helpers, for example, interaction and visible, and those are gonna allow us to specify when we want our hydration to happen. To do that, we simply just wrap whatever component we want in this Hydrate component. We tell it when we want the interior of that component to be hydrated. We also have a prefetch function that allows us to download the code but not actually hydrate the component until we hit that when condition. And then we got this onHydrated callback that we use to go and set that HydrationChip to say that we are hydrated. Now this has been a little bit controversial because in reality, this is really just syntactic sugar over something that React has been able to do for a little while. Most people just haven't used it this way. So let's talk about selective hydration. And the example of that is over in React selective hydration. To do this selective variant, you first lazily load that carousel. We define LazyCarousel as just an import of that carousel, and then we wrap that lazy carousel in a Suspense, and voila, you have selective hydration that moves the hydration of that component until after the page is active. This HydrationSignal component in here is simply just a component that has a useEffect in it, and that useEffect lets us know when that structure inside of the Suspense has been completely hydrated. All right, I'm on the React selective page, and now we can see it just very quickly jumping from unhydrated to rehydrated. Now there's one more variant I'm gonna give you if you don't wanna use the TanStack stuff, and that's the React conditional version. We can see that we're dehydrated and also without styling. I'm gonna glide over this and then we get hydrated and we get the styling back. It's not great, but it's there. This particular example is ReactConditionalHydration. And in this case, what we're doing is creating a gate promise, and that gate promise is based on different intent events like focus in, pointer enter, and click Then we're using this DIY HydrationGate component. And that HyrdrationGate, if it's on the client, is going to use a use to throw if that promise has yet to be fulfilled. And that works because we are wrapped in a Suspense. And that Suspense locks hydration until that hydration gate gets triggered, and that gives you your hydration. Gotta say, in my opinion at least, the syntactic sugar of the TanStack Start hydration is, is really worth it here. Well I hope this video has helped you understand a little bit more about what hydration is and where it fits into React and how it affects performance. Of course, if you have any questions or comments, put them in the comment section right down below. In the meantime, if you like this video, hit that like button. If you really like the video, hit the subscribe button and click on that bell, and you'll be notified the next time a new Blue Collar Coder comes out.