OpenParable
Skip to content
← Back to skills

Jotai

Development
jotai

Jotai is an Agent Skill for development published in the toss/suspensive repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Render-prop components for Jotai atoms: Atom ([value, setValue] like useAtom), AtomValue (read-only like useAtomValue), SetAtom (write-only like useSetAtom) from @suspensive/jotai. Load when reading or writing jotai atoms declaratively in JSX, when async atoms need Suspense boundaries, or when using jotai extensions (jotai-tanstack-query atomWithSuspenseQuery, jotai-cache) with Suspense.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/toss/suspensive/blob/HEAD/packages/jotai/skills/jotai/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/jotai, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

@suspensive/jotai

@suspensive/jotai exports three components — Atom, AtomValue, and SetAtom — that wrap Jotai's useAtom, useAtomValue, and useSetAtom hooks as render-prop components. Each takes an atom prop (any Jotai atom, used as is), an optional options prop (forwarded to the underlying hook, e.g. { store }), and a function as children that receives the hook's return value. This makes it visible in JSX which atoms a subtree uses and which of them trigger Suspense, and lets atoms be read or written inline (inside list rows, conditionals) where hooks would force extracting a component. Peer dependencies: jotai@^2, react@^18 || ^19.

CRITICAL: All three components are client-only ('use client'; render-prop children are functions and cannot cross the RSC serialization boundary). Async atoms suspend — reading an async atom via Atom/AtomValue, or writing a Promise via SetAtom, delegates the pending state to the nearest parent Suspense boundary, so one must exist above the component.

Setup

npm install @suspensive/jotai jotai
import { Atom } from '@suspensive/jotai'
import { atom } from 'jotai'

const countAtom = atom(1)

const Example = () => (
  <Atom atom={countAtom}>
    {([count, setCount]) => (
      <>
        <div>count: {count}</div>
        <button onClick={() => setCount(count + 1)}>+1</button>
      </>
    )}
  </Atom>
)

Core Patterns

Atom — read and write, useAtom interface

children receives [value, setValue]. For an async atom, value is the awaited (resolved) value; the component suspends until the Promise resolves.

import { Atom } from '@suspensive/jotai'
import { Suspense } from '@suspensive/react'
import { atom } from 'jotai'

const countAtom = atom(1)
const asyncDoubleCountAtom = atom(async (get) => {
  await new Promise((resolve) => setTimeout(resolve, 2000))
  return get(countAtom) * 2
})

const Example = () => (
  <Suspense fallback={'pending...'}>
    <Atom atom={asyncDoubleCountAtom}>{([count]) => <>count: {count}</>}</Atom>
  </Suspense>
)

AtomValue — read-only, useAtomValue interface

children receives the value only. Use for read-only atoms (derived async atoms are read-only, so AtomValue is the natural fit).

import { AtomValue } from '@suspensive/jotai'
import { Suspense } from '@suspensive/react'
import { atom } from 'jotai'

const userAtom = atom(async () => {
  const response = await fetch('https://api.example.com/user/1')
  return (await response.json()) as { id: number; name: string }
})

const Example = () => (
  <Suspense fallback={'pending...'}>
    <AtomValue atom={userAtom}>{(user) => <div>{user.name}</div>}</AtomValue>
  </Suspense>
)

SetAtom — write-only, useSetAtom interface

children receives setValue only, so the component does not re-render when the atom's value changes. Writing a Promise to an atom suspends the subtree until the Promise resolves, so async writes also need a parent Suspense.

import { SetAtom } from '@suspensive/jotai'
import { Suspense } from '@suspensive/react'
import { atom } from 'jotai'

const request = async () => fetch('https://api.example.com/count').then((res) => res.json())
const baseAtom = atom(0)

const Example = () => (
  <Suspense fallback={'pending...'}>
    <SetAtom atom={baseAtom}>{(setValue) => <button onClick={() => setValue(request())}>request</button>}</SetAtom>
  </Suspense>
)

Jotai extension atoms (jotai-tanstack-query, jotai-cache, jotai-trpc)

Atoms from Jotai extensions work as the atom prop without wrappers. With atomWithSuspenseQuery, pair Suspense with ErrorBoundary since query errors throw to the boundary.

import { AtomValue } from '@suspensive/jotai'
import { ErrorBoundary, Suspense } from '@suspensive/react'
import { atomWithSuspenseQuery } from 'jotai-tanstack-query'

const userQueryAtom = atomWithSuspenseQuery(() => ({
  queryKey: ['user', 1],
  queryFn: async () => {
    const response = await fetch('https://api.example.com/user/1')
    return (await response.json()) as { id: number; name: string }
  },
}))

const MyPage = () => (
  <ErrorBoundary fallback={({ error }) => <>{error.message}</>}>
    <Suspense fallback={'pending...'}>
      <AtomValue atom={userQueryAtom}>{({ data: user }) => <div key={user.id}>{user.name}</div>}</AtomValue>
    </Suspense>
  </ErrorBoundary>
)

Common Mistakes

[HIGH] No Suspense boundary around async atom components

Wrong:

import { AtomValue } from '@suspensive/jotai'
import { asyncUserAtom } from '~/atoms'

const Example = () => <AtomValue atom={asyncUserAtom}>{(user) => <Profile {...user} />}</AtomValue>

Correct:

import { AtomValue } from '@suspensive/jotai'
import { Suspense } from '@suspensive/react'
import { asyncUserAtom } from '~/atoms'

const Example = () => (
  <Suspense fallback={<Spinner />}>
    <AtomValue atom={asyncUserAtom}>{(user) => <Profile {...user} />}</AtomValue>
  </Suspense>
)

Async atoms suspend; without a boundary the suspension bubbles to the nearest ancestor Suspense or the app root fallback, blanking unrelated UI.

Source: docs/suspensive.org/src/content/en/docs/jotai/AtomValue.mdx

[MEDIUM] Wrapper components created just to read atoms

Wrong:

import { useAtomValue } from 'jotai'
import { cartItemAtomFamily } from '~/atoms'

const CartItemRow = ({ id }: { id: string }) => {
  const item = useAtomValue(cartItemAtomFamily(id))
  return <li>{item.name}</li>
}

const Cart = ({ ids }: { ids: string[] }) => (
  <ul>
    {ids.map((id) => (
      <CartItemRow key={id} id={id} />
    ))}
  </ul>
)

Correct:

import { AtomValue } from '@suspensive/jotai'
import { cartItemAtomFamily } from '~/atoms'

const Cart = ({ ids }: { ids: string[] }) => (
  <ul>
    {ids.map((id) => (
      <AtomValue key={id} atom={cartItemAtomFamily(id)}>
        {(item) => <li>{item.name}</li>}
      </AtomValue>
    ))}
  </ul>
)

Hooks force extracting a child component per call site; the render-prop components read and write atoms inline, keeping the atom usage visible where it happens.

Source: docs/suspensive.org/src/content/en/docs/jotai/motivation.mdx

[MEDIUM] Expecting SetAtom async writes not to suspend

Wrong:

import { SetAtom } from '@suspensive/jotai'
import { atom } from 'jotai'

const request = async () => fetch('https://api.example.com/count').then((res) => res.json())
const baseAtom = atom(0)

const Example = () => (
  <SetAtom atom={baseAtom}>{(setValue) => <button onClick={() => setValue(request())}>request</button>}</SetAtom>
)

Correct:

import { SetAtom } from '@suspensive/jotai'
import { Suspense } from '@suspensive/react'
import { atom } from 'jotai'

const request = async () => fetch('https://api.example.com/count').then((res) => res.json())
const baseAtom = atom(0)

const Example = () => (
  <Suspense fallback={'pending...'}>
    <SetAtom atom={baseAtom}>{(setValue) => <button onClick={() => setValue(request())}>request</button>}</SetAtom>
  </Suspense>
)

Writing a Promise to an atom triggers Suspense until it resolves, so even a write-only SetAtom subtree needs a parent Suspense boundary.

Source: docs/suspensive.org/src/content/en/docs/jotai/SetAtom.mdx

Version

Targets @suspensive/[email protected] with peer dependencies jotai@^2 and react@^18 || ^19.