jotai-ssr

jotai-ssr is a utility library for Jotai to facilitate server-side rendering (SSR). It provides helpers for:

- Hydrating atom values from server to client (and optionally re-hydrating).
- Handling SSR scenarios, including React Server Components and soft navigations in frameworks like Next.js, Remix, and Waku.

This library extends or wraps the existing Jotai SSR utilities to provide a more seamless integration with modern SSR setups.

---

Table of Contents

1. Installation
2. Creating a Safe Store for Each Request
3. Hydration
1. What is Hydration?
2. How to Hydrate an Atom
3. HydrationBoundary
4. Streaming Hydration with Async Atoms
5. Important Notes on Hydration Logic
6. Soft Navigation in SSR Frameworks
7. Re-Hydration

---

Installation

``bash
npm install jotai-ssr


or

When using Jotai in an SSR environment, you must ensure each request has its own store. Relying on a shared, global store (e.g. defaultStore) across requests can lead to data leakage between different users.

To create an isolated store per request, you should use Provider for each layout or page that uses Jotai like so:

`tsx
import { Provider } from 'jotai';

const Page = () => {
return (
{/ Your content /}
);
};
`

If you need to pass a custom store to the Provider, you can do so in one of the following ways:

1. Using useState

`tsx
'use client';

import { createStore, Provider } from 'jotai';
import { useState } from 'react';

const Page = () => {
const [store] = useState(() => createStore());
return {/ your content /};
};
`

2. Using useRef

`tsx
'use client';

import { createStore, Provider } from 'jotai';
import { useRef } from 'react';

const Page = () => {
const storeRef = useRef(undefined);
if (!storeRef.current) {
storeRef.current = createStore();
}
return {/ your content /};
};
`

Both approaches ensure a new store instance is created for each request, preventing data from leaking between different users.

---

Hydration

When data is fetched on the server and passed to the client, you may want to initialize Jotai atoms with those server-side values. This process is called hydration.

$3

Hydration sets up atoms with initial values so that:

- The server-rendered HTML uses the correct initial state.
- Once the client side finishes React hydration, the atom is already in the correct state without causing extra re-renders.

$3

When dealing with SSR, you often have data fetched on the server that needs to be passed to your components and stored in Jotai atoms. To accomplish this, jotai-ssr provides a useHydrateAtoms hook similar to the one in Jotai’s jotai/utils, with a few small differences:

1. No dangerouslyForceHydrate option
2. Exported from jotai-ssr rather than jotai/utils

Apart from these differences, the usage is nearly the same as the official Jotai version. This means you can hydrate your atoms with data like so:

`tsx
'use client'; // If you're using React Server Components (RSC), ensure the file is a Client Component

import { atom, useAtom } from 'jotai';
import { useHydrateAtoms } from 'jotai-ssr';

// Example atom
export const countAtom = atom(0);

interface PageProps {
countFromServer: number;
}

export function Page({ countFromServer }: PageProps) {
// 1. Hydrate the atom with a value fetched on the server
useHydrateAtoms([[countAtom, countFromServer]]);

// 2. Now you can safely use the atom in your component
const [count] = useAtom(countAtom);

return

1. Client-Side Usage:
Despite the term “SSR” in its name, useHydrateAtoms must be called in client code (i.e., a component with 'use client' at the top if you’re using React Server Components).

2. Optional store Parameter:
Just like the Jotai version, you can target a specific store by providing the store option. For example:
`tsx
import { createStore } from 'jotai';

const myStore = createStore();
useHydrateAtoms([[countAtom, 42]], { store: myStore });
`

3. No dangerouslyForceHydrate:
Unlike the original Jotai hook, the jotai-ssr version does not provide a dangerouslyForceHydrate option. If you need more advanced re-hydration behavior, see Re-Hydration.

> Tip: Hydrating an atom does not cause additional re-renders if you do it before using the atom in your component. Make sure to call useHydrateAtoms at the top level of your component (or inside its parent) so that the initial render already has the right atom values.

$3

For React Server Components (RSC) and for a clearer boundary-based approach, jotai-ssr provides a HydrationBoundary component:

`tsx
import { HydrationBoundary } from 'jotai-ssr';
import { countAtom } from './atoms'; // "use client" inside this file

const ServerComponent = async () => {
const countFromServer = await fetchCount();
return (

{/ Components that consume countAtom /}

);
};
`

You can pass an optional options prop, such as { store: myStore }, if you want to hydrate into a specific store.

> Note: HydrationBoundary can be used in both Client and Server Components. However, when using it in a Server Component, the atom definitions must be marked with 'use client'. Also, any value you pass for hydration must be serializable. This is because HydrationBoundary itself is a React Client Component.

---

Streaming Hydration with Async Atoms

Some SSR frameworks (like Next.js) support streaming responses so that part of your UI can render before all data is loaded. With Jotai, you can stream data from the server into async atoms. This allows your components to start rendering in a suspended state, then reveal when the data arrives. Here’s how you can do it with jotai-ssr:

$3

First, define an atom that holds a promise:

`tsx
'use client';

import { atom, useAtomValue } from 'jotai';

// Define an async atom that resolves to a number.
export const countAtom = atom>();

export const CountComponent = () => {
// Jotai will automatically suspend here until the promise resolves
const count = useAtomValue(countAtom);
return

> Note: Because this is an async atom, any component reading it will suspend by default, so you must wrap it with .

$3

Next, in your server-side or edge code, you can fetch the data and hydrate the async atom with a promise:

`tsx
import { HydrationBoundary } from 'jotai-ssr';
import { Suspense } from 'react';
import { countAtom, CountComponent } from './client';

export const StreamingHydration = () => {
// Suppose this fetchCount function returns a Promise
const countPromise = fetchCount();

return (

loading...