Next.js

Hydration

Jotai has support for hydration of atoms with useHydrateAtoms. The documentation for the hook can be seen here.

Sync with router

It's possible to sync Jotai with the router. You can achieve this with atomWithHash:

const pageAtom = atomWithHash('page', 1, {
  replaceState: true,
  subscribe: (callback) => {
    Router.events.on('routeChangeComplete', callback)
    window.addEventListener('hashchange', callback)
    return () => {
      Router.events.off('routeChangeComplete', callback)
      window.removeEventListener('hashchange', callback)
    }
  },
})

This way you have full control over what router event you want to subscribe to.

You can't return promises in server side rendering

It's important to note that you can't return promises with SSR - However, it's possible to guard against it inside the atom definition.

If possible use useHydrateAtoms to hydrate values from the server.

const postData = atom((get) => {
  const id = get(postId)
  if (isSSR || prefetchedPostData[id]) {
    return prefetchedPostData[id] || EMPTY_POST_DATA
  }
  return fetchData(id) // returns a promise
})

Provider

By default, Jotai uses an implicit global store to keep track of atom values. This is what is referred to as "provider-less" mode. This becomes an issue in SSR scenario because this global store is kept alive and is shared between multiple requests, which can lead to bugs and security risks.

To limit the lifetime of the store to the scope of one request, you need to use a Provider at the root of your app (or a subtree if you're using Jotai only for a part of your application).

import { Provider } from 'jotai'

function App({ Component, pageProps }: AppProps) {
  return (
    <Provider>
      <Component {...pageProps} />
    </Provider>
  )
}

In this case:

1. Provider will hold the state of the atoms used in its subtree instead of the global store.
2. Provider's lifetime will be the same as the app itself, and since the app is recreated on each SSR request we essentially limit the lifetime of the store to a single request as well.

SWC plugins

Jotai provides SWC plugins for better DX while developing with Next.js. Find more info in the SWC section.

Examples

Clock

HN Posts

Next.js repo

npx create-next-app --example with-jotai with-jotai-app
# or
yarn create next-app --example with-jotai with-jotai-app

Here's a link.