Someone wanted to learn this too, so Grasp built them a personal learning path.

Create your own
Lesson illustration

Server-Side Authentication Hydration

Hello! Welcome to our next lesson.

Introduction

In our last session, we created a typed AuthContext using the useServerFn hook. This was a major step towards unifying our application's authentication state. We now have a useAuth hook that works on both the server (during rendering) and the client (during navigation).

However, a critical question remains: how does the initial authentication state, determined on the server, get to the client seamlessly? If the client has to re-fetch the user's status on page load, we'll see a jarring "flash of unauthenticated content" (e.g., a "Login" button that quickly changes to "Logout").

This lesson tackles that exact problem, focusing on the learning outcome: Serialize and inject the initial authentication state from the server into the HTML document for client-side hydration. We will demystify the "magic" of how modern SSR frameworks like TanStack Start create a perfectly smooth initial load experience.

1. The Core Problem: The Hydration Gap

In a server-side rendered application, the user's browser first receives a complete HTML document. This document is static. A moment later, the client-side JavaScript loads, "hydrates" the page, and makes it interactive. The time between the initial render and full interactivity is the "hydration gap."

If the server renders the page for an authenticated user, but the client-side code doesn't know this immediately, it might briefly render a default "unauthenticated" UI. This creates a poor user experience. The solution is to pass the initial state from the server to the client along with the HTML.

Do you REALLY need SSR?

To better understand this concept, let's watch a segment from a video by Theo - t3.gg that explains the modern SSR process and introduces the term 'hydration'.

Watch from 08:01 to 13:35. Focus on the explanation of the SSR request lifecycle and the distinction between a page being 'loaded' (the HTML is visible) and 'hydrated' (the JavaScript has taken over and the page is interactive).

As the video explains, the key is to ensure the client-side JavaScript has all the information it needs to take over from the server-rendered HTML without having to re-calculate or re-fetch anything.

2. The Dehydrate-Inject-Hydrate Pattern

The useServerFn hook we used in the previous lesson handles this state transfer for us automatically. It is built on top of TanStack Query and uses a powerful pattern that we can break down into three steps: Dehydrate, Inject, and Hydrate.

Let's explore how this works under the hood by looking at the mechanisms provided by TanStack Query.

Step 1: Dehydration (On the Server)

After our getCurrentUserFn server function runs during the initial request, its result is stored in a server-side instance of a TanStack Query cache. To send this cache state to the client, it must be serialized. This process is called dehydration.

TanStack Query provides a dehydrate function that creates a "frozen," serializable representation of the query cache.

hydration | TanStack Query React Docs

The TanStack Query documentation on hydration provides the API reference for dehydrate. Let's look at its definition.

Read the section on dehydrate. Note that its purpose is to create a 'frozen representation of a cache' that can be passed from server to client.

Step 2: Injection (Into the HTML)

Once the query cache is dehydrated into a plain JavaScript object, it needs to be sent to the client. The standard method is to serialize this object into a JSON string and embed it directly into the outgoing HTML document inside a <script> tag. This attaches the initial state to the global window object.

SSR | TanStack Query React Docs

The TanStack Query SSR guide includes a fantastic, framework-agnostic example of this exact process. It clearly shows how the dehydrated state is stringified and placed into the HTML.

In this resource, focus on the code block under the 'On the Server' heading. Pay close attention to these two lines: const dehydratedState = dehydrate(queryClient) window.__REACT_QUERY_STATE__ = ${JSON.stringify(dehydratedState)}; This is the essence of serializing and injecting the state.

The server-rendered HTML sent to the browser would look something like this:

<html>
  <body>
    <div id="root"><!-- Server-rendered app content --></div>
    <script>
      // The injected, dehydrated state!
      window.__REACT_QUERY_STATE__ = {"mutations":[],"queries":[{"state":{...},"queryKey":["..."]}]};
    </script>
    <!-- Other script tags to load client-side JS -->
  </body>
</html>

Step 3: Hydration (On the Client)

When the client-side JavaScript finally loads, its first job is to look for this injected state. It parses the JSON from window.__REACT_QUERY_STATE__ and uses it to pre-populate its own TanStack Query cache. This process is called hydration.

Because the client's query cache is "hydrated" with the server's data before any components attempt to render, any call to useQuery (or, in our case, useServerFn) will find the data already in the cache and won't trigger a network request.

TanStack Query provides a <Hydrate> component to handle this gracefully.

SSR | TanStack Query React Docs

Let's return to the TanStack Query SSR guide to see the client-side counterpart to the injection step.

Now, review the code block under the 'Client' heading. See how it retrieves dehydratedState from the window object and passes it as a prop to the <Hydrate> component, which wraps the main <App />.

This three-step dance ensures that the client-side application state is perfectly synchronized with the server-rendered state from the very first moment.

3. TanStack Start: The Automation Layer

Now, you might be wondering, "Why didn't we have to write any of this code?"

This is the power of an integrated framework like TanStack Start. It automates the entire Dehydrate-Inject-Hydrate pattern for you. When you use useServerFn:

  1. On the server, TanStack Start executes your server function and populates its internal query cache.
  2. During the render-to-HTML process, its bundler (Vinxi) automatically dehydrates the cache and injects the necessary <script> tag into the final HTML output.
  3. On the client, the entry point file generated by TanStack Start automatically finds this state on the window object and uses it to hydrate the client-side query cache before your application code even runs.

You get the benefits of this complex SSR pattern with the simplicity of a single hook. Understanding the underlying mechanism, however, is crucial for debugging and for appreciating what the framework does for you.

4. A Practical Analogy in Next.js

This pattern isn't unique to TanStack. Most modern SSR frameworks implement a similar concept. Seeing how another popular framework, Next.js, handles it can help solidify your understanding.

Next.js Tutorial - 73 - Server-side Authentication

This video from Codevolution demonstrates server-side authentication in Next.js. It shows a slightly different implementation that achieves the exact same goal: preventing the UI flicker by passing the session from the server.

Watch from 04:43 to 08:41. Notice how the session is fetched on the server in getServerSideProps and passed down as pageProps.session. This prop is then used to initialize the client-side Provider. This is Next.js's way of 'injecting' the initial state.

While the syntax is different (getServerSideProps vs. useServerFn), the principle is identical: fetch data on the server, pass it down with the initial HTML payload, and use it to initialize the client-side state.

Conclusion

In this lesson, we pulled back the curtain on one of the most important concepts in modern SSR: hydration. You now understand how the initial authentication state travels from the server to the client to create a seamless user experience.

Key Takeaways:

  • Hydration is the process of client-side JavaScript taking over the static HTML sent by the server, making it interactive.
  • To prevent UI flickers, the initial application state must be passed from the server to the client.
  • This is achieved through the Dehydrate-Inject-Hydrate pattern:
    1. Dehydrate: Serialize the state on the server (e.g., using TanStack Query's dehydrate).
    2. Inject: Embed the serialized state into the HTML document, typically in a <script> tag.
    3. Hydrate: Use the injected state on the client to initialize the application's state before rendering (e.g., using the <Hydrate> component).
  • Frameworks like TanStack Start automate this entire process when you use tools like useServerFn.

Next Up:

We've successfully transported the initial authentication state to the client. The final step in setting up our context is to ensure our client-side AuthProvider correctly and robustly initializes itself from this hydrated state. In the next lesson, we will focus on the client-side logic required to consume this state and prevent any potential UI mismatches.

Previous lesson
Typed Auth Context for Server & Client
Next lesson
Client-Side Auth Hydration & UI Consistency

Can't find a good explanation? Sign up and we'll make it for you

Sign up