Skip to main content

Deep Dive: SSR Hydration

Archibald supports seamless session hydration from server to client. This ensures that the user's authentication state is available immediately upon page load without extra client-side requests.

How it works​

The following diagram illustrates the lifecycle of a session token from the initial request to client-side hydration:

Detailed Process​

  1. Request Extraction: When the browser requests a page, it automatically includes the authentication cookies (nct for session, ncr for refresh). The AuthModule on the server extracts and validates these tokens.
  2. Server Prefetch: During the server-side rendering phase, the SessionClient (running on the server) calls prefetchUser(). This populates the internal cache with the current user's profile.
  3. Serialization: Archibald serializes the prefetched state into the initial HTML payload via the window.__INITIAL_DATA_CACHE__ and window.__INITIAL_APP_CACHE__ script blocks.
  4. Client Initialization: When the React application bootstraps in the browser, the client-side SessionClient detects the serialized state and hydrates its internal cache immediately.
  5. Instant Availability: Hooks like useUser and useIsLoggedIn return the correct data on the very first render, preventing layout shifts or "flickers" of unauthenticated content.

Configuration​

To enable this behavior, the authenticateOnServer option must be set to true in the SessionClient configuration.

new SessionClient({
    authenticateOnServer: true,
    // ...
});

Troubleshooting​

If hydration is not working, check the following:

  • Ensure that the AuthModule is correctly configured on the server.
  • Verify that the nct (session) cookie is being sent by the browser.
  • Check that the SessionClientProvider is wrapping your application.