npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

jotai-ssr

v0.1.1

Published

Jotai utilities for server-side rendering (SSR)

Downloads

2,279

Readme

jotai-ssr

Jotai utilities for server-side rendering (SSR)

Motivation

This package provides a new SSR utility designed to replace useHydrateAtoms, offering a safer and more flexible way to use Jotai in SSR environments.

This package provides comprehensive support for React Server Components, particularly with the Next.js App Router, addressing several limitations and issues that arise when using Jotai in server-side rendering contexts.

Feedback

This is a new package and we would love to hear your feedback. Related discussion: https://github.com/pmndrs/jotai/discussions/2692

Overview

This package provides 3 boundary components and 1 atom for server-side rendering with Jotai:

  • RenderingBoundary - A boundary component that should be used at the root of components that will be rendered on the server during navigation, such as Next.js's page.tsx, layout.tsx, etc.
  • SuspenseBoundary - A boundary component that should be used at the root of async components wrapped with React.Suspense, but only when the component subtree references atoms that have the potential to change while suspended.
  • HydrationBoundary - A boundary component for hydrating atoms (synchronizing the server-rendered HTML with the client state) on the client side.
  • isHydratingAtom - An atom that can be used to check if atom hydration is in progress.

Installation

npm install jotai-ssr
# or
yarn add jotai-ssr
# or
pnpm add jotai-ssr

Usage

This is a Next.js App Router example:

Define Rendering Boundary

Wrap the components that will be rendered on the server during navigation with RenderingBoundary.

layout.tsx:

import { RenderingBoundary } from 'jotai-ssr'

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

page.tsx:

import { RenderingBoundary } from 'jotai-ssr'

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

Note: RenderingBoundary is used in both React Server Components and React Client Components. RenderingBoundary itself is a React Client Component.

RenderingBoundary creates a new store for subtree that is isolated from the parent store. For example, above LayoutComponent and Component will have their own store. In other words, the store is not shared between layout.tsx and page.tsx.

The store also independent for each request: the store will never be shared between requests.

Sharing Stores between layout and page (Advanced Usage)

If you need to share stores between layout.tsx and page.tsx, you can use the performanceImpactingUseUpperStore option in RenderingBoundary, which will cause an additional re-render after initial hydration.

Why do we need RenderingBoundary?

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. Think following case:

  1. Create const sampleAtom = atom(0)
  2. Set up a Provider in layout.jsx, or render without setting up a Provider anywhere
  3. Change sampleAtom to 1 in page.jsx
  4. Navigate to another page using Link component

In this case, the value of sampleAtom on server-side rendered HTML will be 0, but the value of sampleAtom on the client side will be 1. This will cause a mismatch between server-side rendered HTML and hydration, resulting in an error. To prevent this, use RenderingBoundary to create a new store for each page.

How performanceImpactingUseUpperStore option works

Even if performanceImpactingUseUpperStore is set to true, RenderingBoundary will still create a new store for each request. However, after hydration, it will re-render the subtree once to use the store of the parent component. Because of this re-render, it may impact performance.

Using SuspenseBoundary

Only when the async component wrapped by React.Suspense subtree references atoms that have the potential to change while suspended, use SuspenseBoundary. If there are no atoms that have the potential to change while suspended, you don't need to use SuspenseBoundary.

import { Suspense } from 'react'
import { SuspenseBoundary } from 'jotai-ssr'

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

Note: SuspenseBoundary itself is React Server Component.

Why do we need SuspenseBoundary?

When using React.Suspense, if the component subtree references atoms that have the potential to change while suspended, there is a possibility of errors occurring during page transitions due to mismatches between server-side rendered HTML and hydration. To prevent this, use SuspenseBoundary to create a new store for the suspended subtree.

Hydrating Atoms

Use HydrationBoundary to hydrate atoms at specific points in your component tree. hydrateAtoms props is an array of atom and values to hydrate.

With React Server Components:

import { HydrationBoundary } from 'jotai-ssr'
import { dataAtom } from './atoms'

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

Note: if you use HydrationBoundary in React Server Components, 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);

Detailed explanation is here.

With React Client Components:

'use client'

import { HydrationBoundary } from 'jotai-ssr'
import { idAtom } from './atoms'

function Component({ id }) {
  return (
    <HydrationBoundary hydrateAtoms={[[idAtom, id]]}>
      <ChildComponent />
    </HydrationBoundary>
  )
}

You should use hydrated atoms within the HydrationBoundary component. If you use hydrated atoms outside of the HydrationBoundary component, it may cause mismatches between server-side rendered HTML and hydration.

You can use multiple HydrationBoundary components.

import { HydrationBoundary } from 'jotai-ssr'
import { dataAAtom, dataBAtom } from './atoms'

async function HydrationDataABoundary({ children }) {
  const dataA = await fetch('https://api.example.com/dataA').then((res) => res.json())
  return (
    <HydrationBoundary hydrateAtoms={[[dataAAtom, dataA]]}>
      {children}
    </HydrationBoundary>
  )
}

async function HydrationDataBBoundary({ children }) {
  const dataB = await fetch('https://api.example.com/dataB').then((res) => res.json())
  return (
    <HydrationBoundary hydrateAtoms={[[dataBAtom, dataB]]}>
      {children}
    </HydrationBoundary>
  )
}

function Component() {
  return (
    <div>
      <HydrationDataABoundary>
        <HydrationDataBBoundary>
          <ChildComponent />
        </HydrationDataBBoundary>
      </HydrationDataABoundary>
    </div>
  )
}

Checking Hydration Status

You can use the isHydratingAtom to check if atom hydration is in progress:

import { atom } from 'jotai'
import { isHydratingAtom } from 'jotai-ssr'

function Component() {
  const samplePrimitiveAtom = atom(0)

  const sampleAtom = atom(
    (get) => get(samplePrimitiveAtom),
    (get, set, update) => {
      set(samplePrimitiveAtom, update)
      if (get(isHydratingAtom)) {
        // Do something when atom is hydrating
      } else {
        // Do something when atom is not hydrating
      }
    }
  )
}