New utility to enhance SSR support (for Next.js App Router / React Server Component) #2692

akkadaska · 2024-08-04T05:49:16Z

akkadaska
Aug 4, 2024

First, I'd like to express my gratitude for the development of this fantastic library.

This library supports SSR through the useHydrateAtoms hook. However, when actually developing with Next.js, especially with the App Router, there are situations where the useHydrateAtoms hook alone feels insufficient. In this discussion, I'd like to share and delve into the current limitations of Jotai in Next.js App Router or React Server Components, and propose a new approach to SSR that might address these issues.

Problems

1. Need for proper Provider setup in Next.js `layout.jsx` and `page.jsx`

In Next.js, when navigating pages using the Link component, layout.jsx is not re-rendered, but page.jsx is. Because of this structure, if page.jsx references a Store that is in layout.jsx or is global, there's a possibility of errors occurring during page transitions due to mismatches between server-side rendered HTML and hydration.

Steps:

Create const sampleAtom = atom(0)
Set up a Provider in layout.jsx, or render without setting up a Provider anywhere
Change sampleAtom to 1 in page.jsx
Navigate to another page and then return

In step 4, an error occurs because during server-side rendering of page.jsx, the value of sampleAtom is referenced as the initial value 0, but during client-side hydration, it's referenced as 1.

Therefore, proper Provider setup is necessary in files like layout.jsx and page.jsx.

2. Similar issues with `Suspense`

When using Suspense, issues similar to problem 1 can occur.

Steps:

Create const sampleAtom = atom(0)
Set up a Provider in page.jsx
Change sampleAtom to 1 while an asynchronous component is still suspended
The asynchronous component is displayed

In step 4, an error occurs because during server-side rendering, the value of sampleAtom is referenced as the initial value 0, but during client-side hydration, it's referenced as 1.

3. Multiple locations where Atom hydration is desired

In React Server Components, it's common to create components for each fetch source since fetching can be done within components. Therefore, when wanting to hydrate Atoms in multiple components, hydration would occur in multiple places, which is not anticipated by the useHydrateAtoms hook.

4. Ability to reference Atoms before hydration

It's possible to reference an Atom before hydrating it with the useHydrateAtoms hook, which is not an intended implementation.

Solutions

To address these issues, I propose the following three Boundary components:

1. `RenderingBoundary`

Source code: https://github.com/akkadaska/jotai-ssr/blob/main/src/jotai-ssr/RenderingBoundary.tsx

The RenderingBoundary component is used at rendering boundaries such as layout.jsx and page.jsx. This component sets up a Provider to prevent errors caused by mismatches between server-side rendered HTML and hydration during page transitions.

Typically, this is sufficient:

// layout.jsx
export default function Layout({ children }) {
  return (
    <html>
      <body>
        <RenderingBoundary>
          {children}
        </RenderingBoundary>
      </body>
    </html>
  )
}

// page.jsx
export default function Page() {
  return (
    <RenderingBoundary>
      <Component />
    </RenderingBoundary>
  )
}

By default, the Stores in layout.jsx and page.jsx are completely independent, and page.jsx cannot access the Store in layout.jsx. This prevents errors caused by mismatches between server-side rendered HTML and hydration during page transitions.

However, for users who absolutely need to share Stores between layout.jsx and page.jsx, we provide the performanceImpactingUseUpperStore option, which can be used with the understanding that it may impact performance. Setting this to true in page.jsx allows sharing of Stores between layout.jsx and page.jsx.

// page.jsx
export default function Page() {
  return (
    <RenderingBoundary performanceImpactingUseUpperStore>
      <Component />
    </RenderingBoundary>
  )
}

When performanceImpactingUseUpperStore is enabled, server-side rendering and client-side hydration use a Store independent of layout.jsx, but afterwards, page.jsx is re-rendered using the Store from layout.jsx via useEffect, and from then on, the Store is shared between layout.jsx and page.jsx.

2. `SuspenseBoundary`

Source code: https://github.com/akkadaska/jotai-ssr/blob/main/src/jotai-ssr/SuspenseBoundary.tsx

The SuspenseBoundary component is used within Suspense components. This component should only be used when there's a possibility that Atoms dependent on the suspended component might change during suspension. In other words, it's unnecessary if there's no chance of Atoms changing during suspension.

function Component() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <SuspenseBoundary>
        <AsyncComponent />
      </SuspenseBoundary>
    </Suspense>
  )
}

The implementation of the SuspenseBoundary component is similar to when performanceImpactingUseUpperStore is enabled in the RenderingBoundary component.

3. `HydrationBoundary`

Source code: https://github.com/akkadaska/jotai-ssr/blob/main/src/jotai-ssr/HydrationBoundary.tsx

The HydrationBoundary component is used where you want to hydrate Atoms. By specifying the target Atom and its value, descendant components can reference the hydrated Atom.

async function Component() {
  const data = await fetch('https://api.example.com/data').then((res) => res.json())
  return (
    <HydrationBoundary hydrateAtoms={[[dataAtom, data]]}>
      <ChildComponent />
    </HydrationBoundary>
  )
}

Unlike the useHydrateAtoms hook, the HydrationBoundary component allows setting the same Atom multiple times. This is useful when one Atom updates the value of another Atom.

HydrationBoundary scopes the Atoms to be hydrated using the ScopeProvider from jotai-scope. This ensures that hydrated Atoms can only be referenced within that scope. Also, since the hydration process completes before child components are rendered, there's no issue even if the same Atom is set multiple times.

Note that in the implementation, we provide isHydratingAtom to check if Atom hydration is in progress, but this is not mandatory. This is a feature I proposed in another discussion.

This concludes my proposal. I welcome your thoughts and feedback. If you find this proposal useful, I hope you'll consider incorporating it into Jotai's core. Thank you for your consideration.

Answered by akkadaska

Aug 12, 2024

New jotai-ssr lib was released!
https://www.npmjs.com/package/jotai-ssr

Please give us a feedback!

View full answer

dai-shi · 2024-08-06T12:52:16Z

dai-shi
Aug 6, 2024
Maintainer

Thanks for opening up a discussion.

the current limitations of Jotai in Next.js App Router or React Server Components

So, it's a new problem. You don't have such issues with Pages Router, right?

In Next.js, when navigating pages using the Link component, layout.jsx is not re-rendered, but page.jsx is.

Interesting. I wasn't aware such a behavior. That sounds tricky.
If it's client routing, nothing will go wrong, but it sounds like the issue you describe comes with SSR (as it says hydration error) with subsequent navigation.
It sounds to me like a Next.js specific issue.

To address these issues, I propose the following three Boundary components:

I'm not sure if I follow every details, but it seems like a good step.
We should get more feedback on it.

If you find this proposal useful, I hope you'll consider incorporating it into Jotai's core.

As I said, we don't consider this as the Jotai core feature. It's an integrations like other integrations.
So, I would like to invite you to https://github.com/jotaijs and you can maintain jotai-ssr there.
It's also fine to have it under your profile if you want. How does that sound?

2 replies

akkadaska Aug 6, 2024
Author

Thank you for replying.

So, it's a new problem. You don't have such issues with Pages Router, right?

Yes, this is a new problem related to App Router (and React Server Component).

Interesting. ... It sounds to me like a Next.js specific issue.

layout.jsx is not re-rendered, but page.jsx is when navigating is a designed behavior of Next.js.
in https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#layouts

A layout is UI that is shared between multiple routes. On navigation, layouts preserve state, remain interactive, and do not re-render.

As I said, we don't consider this as the Jotai core feature. It's an integrations like other integrations.
Sorry, I agree with you, this features are not for core, should be isolated to other library, and my current implementation does not overwrite core functions.

I'm ready for creating for jotai-ssr library. I prefer to maintain on jotaijs org, so would you please invite to https://github.com/jotaijs ? I promise I will contribute fully.

dai-shi Aug 6, 2024
Maintainer

Sent an invitation!

akkadaska · 2024-08-12T13:02:53Z

akkadaska
Aug 12, 2024
Author

New jotai-ssr lib was released!
https://www.npmjs.com/package/jotai-ssr

Please give us a feedback!

0 replies

akkadaska · 2024-08-12T15:38:58Z

akkadaska
Aug 12, 2024
Author

I realized that when using HydrationBoundary in a React Server Component, the file that defines a hydrated atom must include the 'use client' directive, like this:

'use client'

import { atom } from 'jotai';

export const someAtom = atom(0);

This requirement exists because when HydrationBoundary is used in a React Server Component, its props are passed from a React Server Component to a React Client Component. Therefore, the props (i.e., atoms) should follow React's Serializable types returned by Server Components rules.

Notably, these are not supported:

Functions that are not exported from client-marked modules or marked with 'use server'.

Jotai atoms include functions. To paraphrase the above quote, functions or atoms that are exported from client-marked modules can be passed from a React Server Component to a React Client Component. Therefore, adding the 'use client' directive to the atom definition file works well.

At least this approach works in Next.js App Router. However, I'm not sure if adding the 'use client' directive to the atom definition file is the best solution.

2 replies

dai-shi Aug 13, 2024
Maintainer

I think it's reasonable and necessary to add 'use client' for atom definition files.

akkadaska Aug 13, 2024
Author

Thank you!

I have thought about this thoroughly and concluded that this is the optimal approach. Since Jotai's Atom checks identity by reference, we need to pass it as a prop from a React Server Component to a React Client Component. (Tanstack Query's HydrationBoundary can do this because the identifier, QueryKey, is serializable, which does not apply to Jotai.)

I will update README.

akkadaska · 2024-08-18T06:28:16Z

akkadaska
Aug 18, 2024
Author

I had a misunderstanding about why RenderingBoundary was necessary. I apologize for proceeding with the library development based on this incorrect understanding.

However, even with the correct understanding, this library, including RenderingBoundary, still solves the problem.

Misunderstanding

My incorrect understanding was as follows:

In Next.js, when navigating pages using the Link component, layout.jsx is not re-rendered, but page.jsx is. Because of this structure, if page.jsx references a Store that is in layout.jsx or is global, there's a possibility of errors occurring during page transitions due to mismatches between server-side rendered HTML and hydration.

Steps:

Create const sampleAtom = atom(0)

Set up a Provider in layout.jsx, or render without setting up a Provider > anywhere

Change sampleAtom to 1 in page.jsx

Navigate to another page and then return

In step 4, an error occurs because during server-side rendering of page.jsx, the value of sampleAtom is referenced as the initial value 0, but during client-side hydration, it's referenced as 1.

Therefore, proper Provider setup is necessary in files like layout.jsx and page.jsx.

In reality, since navigation using the Link component is client-side, rendering occurs on the client side, so this problem likely doesn't occur.

The mismatch between HTML and hydration was a known issue:
#1982 (reply in thread)

Simply move the component that calls useHydrateAtoms to the top of the component tree, this will ensure that all children will render with the correct value.

This issue can also be resolved by using HydrationBoundary for hydration and ensuring that components referencing Atoms dependent on hydration are descendants of it. The concept of HydrationBoundary allows hydration to always occur at a higher level than dependent components without creating additional hydration-specific components.

New Problem

With client-side navigation using the Link component, a different problem was occurring.

The following is an issue when trying to share Jotai's Store at the layout.tsx level without setting up a Provider in page.tsx. If you set up the Provider in page.tsx and Jotai's Store is independent within each page, this problem doesn't occur.

A Next.js project reproducing these issues can be found here:
https://github.com/akkadaska/jotai-nextjs-link-navigation

Problem with `useHydrateAtoms`

Consider the following setup:

Set up a Provider in layout.jsx, but not in page.jsx
Create export const sampleAtom = atom('')
Navigate using the Link component from a page where sampleAtom is hydrated with 'a' to a page where it should be hydrated with 'b'

In this case, sampleAtom should become 'b' after navigation, but it remains 'a'.

This is because useHydrateAtoms is designed to hydrate each Atom only once. With client-side navigation, the hydration history is retained, causing this issue.

Problem when removing the hydration count limit

The above error could seemingly be resolved by removing the hydration count limit from useHydrateAtoms. Also, the HydrationBoundary provided by jotai-ssr doesn't limit the number of hydrations, so it could potentially solve the problem.

However, a different issue arises. In React's development mode (when running the next dev command), the following error occurs:

Warning: Cannot update a component (`ShowAtom`) while rendering a different component (`HydrationBoundary`). To locate the bad setState() call inside `HydrationBoundary`, follow the stack trace as described in https://reactjs.org/link/setstate-in-render

(Note: This error doesn't appear in React's production mode (when running the next start command), but this doesn't mean the problem is actually solved; it's just that the error isn't output. For example, errors like "Missing "key" prop for element in iterator" also don't appear in production mode.)

In fact, when hydrating with HydrationBoundary during the rendering of the post-navigation page, the value of sampleAtom changes, but this causes the pre-navigation page to re-render because it's also referencing sampleAtom.

To understand this more abstractly, navigation is the process of switching from the current Page Component to a new Page Component. In React, you shouldn't render other components while rendering a new Page Component. However, when hydrating in the new Page Component, changes are made to the Store shared between the current and new Page Components, causing the current Page Component to re-render. There's a rule that Atoms hydrated by HydrationBoundary should only be referenced by its descendants, but when HydrationBoundary itself is re-rendered, this rule is actually being broken.

According to the official React explanation:

In the rare case that you intentionally want to change the state of another component as a result of rendering, you can wrap the setState call into useEffect.

To achieve this, we need to avoid making changes to the Store shared between the current and new Page Components until rendering is complete, and then make changes after rendering is finished.

The performanceImpactingUseUpperStore of RenderingBoundary in jotai-ssr accomplishes exactly this.

First, it renders the post-navigation Page Component in page.tsx using a completely independent Store. Naturally, being independent, it doesn't affect the pre-navigation page or Layout. When rendering is successfully completed, components depending on sampleAtom are only within the HydrationBoundary of the post-navigation page.

Next, the useEffect hook of RenderingBoundary switches the reference from the independent Store to the shared Store. When switching, HydrationBoundary is re-rendered and hydration is re-executed. At this point, when making changes to the common Store through hydration, it doesn't affect the components that were previously referencing the independent Store. This ensures that the pre-navigation page and Layout are not re-rendered, and only the post-navigation page is re-rendered. Moreover, other components referencing Atoms that are being hydrated are within the HydrationBoundary, so they don't affect the pre-navigation page or Layout. This allows the navigation to occur without issues.

Summary

Using HydrationBoundary can prevent writing patterns that might cause mismatches between server-side rendered HTML and client-side hydration.
Using HydrationBoundary and RenderingBoundary can solve problems that occur during client-side navigation.
jotai-ssr remains useful.
README should be updated.

Future Challenges

When performanceImpactingUseUpperStore of RenderingBoundary is enabled, hydration is executed twice. This behavior could be problematic if hydration has side effects.
In cases of navigation not using the Link component in Next.js, such as directly accessing a URL or navigating with a regular a tag, re-rendering is unnecessary even with performanceImpactingUseUpperStore of RenderingBoundary enabled. If there's a way to detect this, we could potentially re-render only when truly necessary. However, this would mean the number of hydration executions varies depending on the navigation method, which could complicate the aforementioned issue of hydration with side effects.
The problem could potentially be solved by scoping Atoms hydrated by HydrationBoundary to only its descendants. The ScopeProvider from jotai-scope could be applied here. With this approach, hydration would only need to happen once. However, when hydrating Derived Atoms, a precise understanding of ScopeProvider's behavior is necessary. Also, ScopeProvider might face issues with side effects. Computed atoms get needlessly triggered again jotaijs/jotai-scope#25
Conversely, we could consider an approach where Atoms that need to reference the parent Store are passed as props to RenderingBoundary. However, at this point, I haven't figured out how to implement this.

5 replies

dai-shi Aug 18, 2024
Maintainer

I apologize for proceeding with the library development based on this incorrect understanding.

Don't worry. We need iterations.

I actually wonder if the hydration error is Next.js specific.
Would anyone like to try Remix, Astro, and, Waku?

akkadaska Aug 18, 2024
Author

The same issue occurred in Remix with the Link component, as described here: https://github.com/akkadaska/jotai-remix-link-navigation .

Additionally, I discovered a new Remix-specific issue when using slugs or URL path parameters and navigating to another slug with the Link component. It appears that the Provider, RenderingBoundary, and HydrationBoundary components are not re-rendered after navigation. As a workaround, adding a key prop and setting it to the slug value works well.

I believe that this issue is not limited to Next.js but may also affect Remix and other frameworks that support client-side navigation of page components with server-side rendering.

dai-shi Aug 18, 2024
Maintainer

Can you make a reproduction with Waku? That will help me understand the problem.
https://stackblitz.com/github/dai-shi/waku/tree/main/examples/01_template (oops, it's not working now 😓 ) or npm create waku@next.

akkadaska Sep 1, 2024
Author

Reproduction with Waku: https://github.com/akkadaska/jotai-waku-link-navigation

When the Jotai store is defined in the root layout and shared between pages using the navigation Link component, the following issues occur:

Slug-Based Pages: When using Jotai in pages with slugs, the slug needs to be set as the key prop for HydrationBoundary, Provider, or RenderingBoundary to ensure these components re-render correctly.
Hydration Issues with useHydrateAtoms: Similar to Next.js and Remix, useHydrateAtoms exhibits unintended behavior where atoms are not hydrated during navigation.
Component Update Errors: Using HydrationBoundary without RenderingBoundary results in an error, similar to Next.js and Remix: "Cannot update a component (ShowAtom) while rendering a different component (HydrationBoundary)".
Successful Approach: Using HydrationBoundary with RenderingBoundary works as expected.

Additionally, a Waku-specific error not encountered with Next.js and Remix occurs:

Hydration Mismatch Error: Directly accessing pages that utilize useHydrateAtoms or HydrationBoundary without RenderingBoundary leads to a hydration mismatch error: "Hydration failed because the server rendered HTML didn't match the client. As a result, this tree will be regenerated on the client. This can happen if a SSR-ed Client Component used:..."

Finally, an issue unrelated to Jotai occurs when importing modules containing the 'use client'; directive (like Provider, HydrationBoundary) from server components (pages/**/*.tsx):

Server-Side Import Error: Importing these modules from server components causes a server error. For instance, importing Provider in pages/index.tsx results in this error:

Cannot find module '/node_modules/jotai/esm/react.mjs' imported from /path-to-project/node_modules/waku/dist/lib/middleware/dev-server-impl.js

akkadaska Sep 1, 2024
Author

Conclusion of Jotai with Next.js, Remix and Waku

With slug pages

Remix and Waku: setting the slug as key props of Provider, HydrationBoundary or RenderingBoundary is required to make the Jotai related components re-render when navigating by Link component.
Next.js: not required to set the slug as key props, however, for the future case that Next.js modify the client-side rendering behavior, it may be required to set the slug as key props.

Using Jotai Provider defined in Root Layout component and shared by pages

`useHydrateAtoms` hook

All 3 frameworks: atoms are not hydrated when navigating by Link component when from and to pages uses same atoms.

`HydrationBoundary` without `RenderingBoundary`

All 3 frameworks: "Cannot update a component while rendering a different component" error occurs when navigating by Link component when from and to pages uses same atoms. This is a React error, not framework specific error.

`HydrationBoundary` with `RenderingBoundary` and `performanceImpactingUseUpperStore` enabled

All 3 frameworks: works without any issues.

Updated (Aug. 3, 2024)

Mismatch of server-rendered HTML and hydration with Waku was caused by my mistakes and with correct implements, it works well. I am very sorry for this.
akkadaska/jotai-waku-link-navigation@4a51737

dai-shi · 2024-09-01T13:20:29Z

dai-shi
Sep 1, 2024
Maintainer

I think I understand at least one miscommunication.
useHydrateAtoms is only for the first render, and subsequent renders must use useEffect.
So, hydration doesn't happen with <Link> navigation in my terminology.

Here's the modified example: https://stackblitz.com/edit/github-dfyxta?file=src%2Fcomponents%2FRootLayoutWrapper.tsx,src%2Fpages%2F_layout.tsx,src%2Fcomponents%2Fuse-hydrate-atom.tsx

9 replies

akkadaska Oct 3, 2024
Author

Current my idea of when atoms should be set (still under consideration)

Timing	Within Isolated RB	Within Upper Ref RB
SSR(Direct Navigate)	Initial Render	Initial Render
Client-side Navigate	Initial Render	Effect
Re-render-HB	Effect	Effect
Mount-HB after navigation	Initial Render	Initial Render

RB: RenderingBoundary, HB: HydrationBoundary

akkadaska Oct 5, 2024
Author

I believe this is the ideal way to set an Atom.

@dai-shi , I am planning to implement jotai-ssr to support this approach. I would greatly appreciate it if you could share your thoughts on this.

Rules and Atom Set Timing

Rules

jotai-ssr provides two components.

`RenderingBoundary`

This component defines a rendering boundary based on routing. Typically, a new store is generated inside this boundary, but it can also use an upper-level store if specified through options.

For libraries like the Next.js App Router, which avoid re-rendering parts of the layout during client-side navigation, consider the following structure:

Layout
|_ Page1
   |_ Component that uses Jotai atom
|_ Page2
   |_ Component that uses Jotai atom

Using separate stores for Page1 and Page2

If you do not want to share stores between Page1 and Page2 during client-side navigation, place RenderingBoundary within each of these pages.

// Page1.tsx and Page2.tsx
import { RenderingBoundary } from "jotai-ssr";

export default function Page() {
  return (
    <RenderingBoundary>
      {
        // Component that uses Jotai atom
      }
    </RenderingBoundary>
  );
}

Using a shared store between Page1 and Page2

If you want to share the store between Page1 and Page2 during client-side navigation, place RenderingBoundary in the Layout and specify the option to use the upper-level store in RenderingBoundary within each page.

// Layout.tsx
import { RenderingBoundary } from "jotai-ssr";

export default function Layout({ children }) {
  return <RenderingBoundary>{children}</RenderingBoundary>;
}

// Page1.tsx and Page2.tsx
import { RenderingBoundary } from "jotai-ssr";

export default function Page() {
  return (
    <RenderingBoundary useUpperStore>
      {
        // Component that uses Jotai atom
      }
    </RenderingBoundary>
  );
}

`HydrationBoundary`

This component hydrates atoms and defines a boundary within which atoms can be used. It can set atom values not only during SSR hydration but also for client-side navigation or other client-side rendering.

The rules are as follows:

HydrationBoundary must always be placed inside a RenderingBoundary.
Atoms with values set in HydrationBoundary can only be referenced/updated inside this boundary. This is true even if the RenderingBoundary uses the upper-level store. For example, if RenderingBoundary is in the Layout and RenderingBoundary with the upper store is in the Page, an atom intended to be referenced by both must only be hydrated in the Layout.
The same atom cannot have multiple HydrationBoundary instances within a single RenderingBoundary. If you need multiple instances, wrap each in a separate RenderingBoundary without referring to the upper-level store, or use the ScopeProvider from jotai-scope to separate them.

// Within RenderingBoundary

// OK
<>
  <HydrationBoundary hydrateAtoms={[[atom1, value1]]}>
    <ComponentUsingAtom1 />
  </HydrationBoundary>
  <HydrationBoundary hydrateAtoms={[[atom2, value2]]}>
    <ComponentUsingAtom2 />
  </HydrationBoundary>
</>

// OK
<HydrationBoundary atom={atom1} value={value}>
  <HydrationBoundary atom={atom1} value={anotherValue}>
    <ComponentUsingAtom1 />
  </HydrationBoundary>
</HydrationBoundary>

// NG
<>
  <HydrationBoundary hydrateAtoms={[[atom1, value1]]}>
    <ComponentUsingAtom1 />
  </HydrationBoundary>
  <HydrationBoundary hydrateAtoms={[[atom1, value2]]}>
    <ComponentUsingAtom1 />
  </HydrationBoundary>
</>

// OK
<RenderingBoundary>
  <HydrationBoundary hydrateAtoms={[[atom1, value1]]}>
    <ComponentUsingAtom1 />
  </HydrationBoundary>
</RenderingBoundary>
<RenderingBoundary>
  <HydrationBoundary hydrateAtoms={[[atom1, value2]]}>
    <ComponentUsingAtom1 />
  </HydrationBoundary>
</RenderingBoundary>

Timing for Setting Atom Values in `HydrationBoundary`

Ideally, atom values should be set during the initial render to avoid unnecessary re-renders or flickering. However, in certain conditions, setting atom values during render violates React's rules. In such cases, use useEffect to set the values.

The timing is as follows:

Timing	Within Isolated RB	Within Upper Ref RB
SSR (Direct Navigation)	Initial Render	Initial Render
Client-side Navigation	Initial Render	Effect
Re-render-HB	Effect	Effect
Mount-HB after navigation	Initial Render	Initial Render

RB: RenderingBoundary, HB: HydrationBoundary

SSR (Direct Navigation)

Jotai atoms are used within Client Components. Client Components are SSR-rendered during direct navigation, where the entire root layout is rendered.

Within Isolated RB

If RenderingBoundary does not specify useUpperStore, an independent store is generated for each Layout and Page component. Only one HydrationBoundary is present to hydrate a given atom within this isolated RenderingBoundary. Therefore, the atom is hydrated before being referenced, making it safe to set the atom values during the initial render.

Even if RenderingBoundary specifies useUpperStore, rendering during SSR is performed from the root layout. As long as each independent RenderingBoundary contains only one HydrationBoundary, setting atom values during the initial render is safe.

Client-side Navigation

During client-side navigation, only the required parts are re-rendered, and the upper RenderingBoundary might not be remounted.

Within Isolated `RenderingBoundary`

If RenderingBoundary has its own independent store, the RenderingBoundary and HydrationBoundary of the new page are newly mounted. The atom is not yet referenced anywhere, so setting atom values during the initial render is safe.

Within a `RenderingBoundary` Referencing the Upper Store

If RenderingBoundary references the upper store via useUpperStore, the atom might already be referenced by other components. React rules prohibit updating existing state (atom values) during render, so you need to use useEffect to set the values.

In particular, for Next.js App Router, if you navigate to the same page component by changing the path parameter (slug), the entire page (RenderingBoundary) will be newly mounted. If atom values are set during the initial render of this new page, the previous page will re-render. In this case, you need to set the atom values using useEffect.

Re-render-HB

When a HydrationBoundary is re-rendered, atom values must be set again. However, updating values during render when the atom is already referenced violates React’s rules, so you should use useEffect to set the values.

Specifically, in frameworks like Remix or Waku, if you navigate to the same page component by changing the path parameter (slug), the entire page (RenderingBoundary) will not be remounted. Instead, re-rendering will occur due to the change in props. In this case, you need to use useEffect to set the atom values.

Mount-HB after Navigation

When a new HydrationBoundary is mounted after navigation, atom values can be set during the initial render because they are not yet referenced.

Conclusion

By properly using RenderingBoundary and HydrationBoundary and implementing them according to the rules above, atom values can be set optimally for any type of rendering, including SSR.

dai-shi Oct 5, 2024
Maintainer

Not sure every detail, but I think I get the overall idea. I'm curious how <RenderingBoundary useUpperStore> works, or why it's required. But if it's required, it's required...

akkadaska Oct 5, 2024
Author

Without <RenderingBoundary useUpperStore>, we need to create store per page and they are isolated.

Indeed, I don't know how much this option needed.

I will reconsider,

akkadaska Jan 4, 2025
Author

After developing with Jotai in Next.js App Router, I realized that among the cases I thought needed consideration, only a small subset is actually used in practice. For other cases, instead of implementing complex handling logic within the library, it is more practical to provide comprehensive documentation so users can follow the appropriate rules when implementing. Based on these reflections, I have revamped the features provided by the jotai-ssr library and added detailed rules and information to the README to help users utilize Jotai properly in SSR environments.

jotaijs/jotai-ssr#11

jotai-ssr primarily provides the following:

A modified and extended version of useHydrateAtoms from jotai/util:
- Performs hydration even for the same atom when remounted (does not maintain an internal hydratedMap).
- Offers a "Re-Hydrate" option that re-hydrates atoms during re-renders.
A HydrationBoundary component that makes the useHydrateAtoms functionality easier to use in Server Components.

dai-shi · 2024-09-01T13:25:04Z

dai-shi
Sep 1, 2024
Maintainer

Finally, an issue unrelated to Jotai occurs when importing modules containing the 'use client'; directive (like Provider, HydrationBoundary) from server components (pages/**/*.tsx):

That sounds like a bug. I wonder if we can create a minimal reproduction.

1 reply

dai-shi Sep 2, 2024
Maintainer

dai-shi/waku#863 (comment)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New utility to enhance SSR support (for Next.js App Router / React Server Component) #2692

{{title}}

Replies: 6 comments 19 replies

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

Select a reply

New utility to enhance SSR support (for Next.js App Router / React Server Component) #2692

akkadaska Aug 4, 2024

Problems

1. Need for proper Provider setup in Next.js layout.jsx and page.jsx

2. Similar issues with Suspense

3. Multiple locations where Atom hydration is desired

4. Ability to reference Atoms before hydration

Solutions

1. RenderingBoundary

2. SuspenseBoundary

3. HydrationBoundary

Replies: 6 comments · 19 replies

dai-shi Aug 6, 2024 Maintainer

akkadaska Aug 6, 2024 Author

dai-shi Aug 6, 2024 Maintainer

akkadaska Aug 12, 2024 Author

akkadaska Aug 12, 2024 Author

dai-shi Aug 13, 2024 Maintainer

akkadaska Aug 13, 2024 Author

akkadaska Aug 18, 2024 Author

Misunderstanding

New Problem

Problem with useHydrateAtoms

Problem when removing the hydration count limit

Summary

Future Challenges

dai-shi Aug 18, 2024 Maintainer

akkadaska Aug 18, 2024 Author

dai-shi Aug 18, 2024 Maintainer

akkadaska Sep 1, 2024 Author

akkadaska Sep 1, 2024 Author

Conclusion of Jotai with Next.js, Remix and Waku

With slug pages

Using Jotai Provider defined in Root Layout component and shared by pages

useHydrateAtoms hook

HydrationBoundary without RenderingBoundary

HydrationBoundary with RenderingBoundary and performanceImpactingUseUpperStore enabled

Updated (Aug. 3, 2024)

dai-shi Sep 1, 2024 Maintainer

akkadaska Oct 3, 2024 Author

akkadaska Oct 5, 2024 Author

Rules and Atom Set Timing

Rules

RenderingBoundary

Using separate stores for Page1 and Page2

Using a shared store between Page1 and Page2

HydrationBoundary

Timing for Setting Atom Values in HydrationBoundary

SSR (Direct Navigation)

Within Isolated RB

Client-side Navigation

Within Isolated RenderingBoundary

Within a RenderingBoundary Referencing the Upper Store

Re-render-HB

Mount-HB after Navigation

Conclusion

dai-shi Oct 5, 2024 Maintainer

akkadaska Oct 5, 2024 Author

akkadaska Jan 4, 2025 Author

dai-shi Sep 1, 2024 Maintainer

dai-shi Sep 2, 2024 Maintainer

akkadaska
Aug 4, 2024

1. Need for proper Provider setup in Next.js `layout.jsx` and `page.jsx`

2. Similar issues with `Suspense`

1. `RenderingBoundary`

2. `SuspenseBoundary`

3. `HydrationBoundary`

Replies: 6 comments 19 replies

dai-shi
Aug 6, 2024
Maintainer

akkadaska Aug 6, 2024
Author

dai-shi Aug 6, 2024
Maintainer

akkadaska
Aug 12, 2024
Author

akkadaska
Aug 12, 2024
Author

dai-shi Aug 13, 2024
Maintainer

akkadaska Aug 13, 2024
Author

akkadaska
Aug 18, 2024
Author

Problem with `useHydrateAtoms`

dai-shi Aug 18, 2024
Maintainer

akkadaska Aug 18, 2024
Author

dai-shi Aug 18, 2024
Maintainer

akkadaska Sep 1, 2024
Author

akkadaska Sep 1, 2024
Author

`useHydrateAtoms` hook

`HydrationBoundary` without `RenderingBoundary`

`HydrationBoundary` with `RenderingBoundary` and `performanceImpactingUseUpperStore` enabled

dai-shi
Sep 1, 2024
Maintainer

akkadaska Oct 3, 2024
Author

akkadaska Oct 5, 2024
Author

`RenderingBoundary`

`HydrationBoundary`

Timing for Setting Atom Values in `HydrationBoundary`

Within Isolated `RenderingBoundary`

Within a `RenderingBoundary` Referencing the Upper Store

dai-shi Oct 5, 2024
Maintainer

akkadaska Oct 5, 2024
Author

akkadaska Jan 4, 2025
Author

dai-shi
Sep 1, 2024
Maintainer

dai-shi Sep 2, 2024
Maintainer