atom-context
v0.9.0
Published
A simple react context that work in RSC and client components.
Maintainers
mattiaz9Readme
atom-context
Tiny typed context atoms for React Server Components and Client Components.
atom-context gives you a small per-request store for RSC and a matching client-side atom so values
can be initialized on the server, passed through a client boundary, and read or updated by client
components without wiring a React context provider tree.
Installation
pnpm add atom-context @nanostores/reactReact 19 or newer is required. @nanostores/react is used by the examples below to subscribe to
client atoms from React components.
What It Provides
getServerContextAtomfromatom-context/server: a server-only per-request atom backed by Reactcache.AtomContextProviderfromatom-context: a client component that seeds a client atom from a server value.getClientContextAtomfromatom-context: a client-side Nanostores atom for reading and updating the value by key.
The server helper is exported from atom-context/server so server-only code stays out of the
client-safe root entrypoint.
Usage
Create a shared key and type for the value you want to pass through the tree.
// user-context.ts
export type UserContext = {
id: string
name: string
}
export const userContextKey = "app:user"Seed the value in a Server Component and bridge it to client components with AtomContextProvider.
// app/layout.tsx
import { AtomContextProvider } from "atom-context"
import { getServerContextAtom } from "atom-context/server"
import { userContextKey, type UserContext } from "./user-context"
export default async function RootLayout({ children }: { children: React.ReactNode }) {
const user: UserContext = await getCurrentUser()
const userAtom = getServerContextAtom(userContextKey, user)
return (
<html>
<body>
<AtomContextProvider contextKey={userContextKey} serverValue={userAtom.value}>
{children}
</AtomContextProvider>
</body>
</html>
)
}Read the same value later in another Server Component during the same request.
// app/profile/page.tsx
import { getServerContextAtom } from "atom-context/server"
import { userContextKey, type UserContext } from "../user-context"
export default function ProfilePage() {
const user = getServerContextAtom<UserContext>(userContextKey)
return <h1>{user.value.name}</h1>
}Read and update the bridged atom from a Client Component.
"use client"
import { getClientContextAtom } from "atom-context"
import { useStore } from "@nanostores/react"
import { userContextKey, type UserContext } from "./user-context"
export function UserBadge() {
const store = getClientContextAtom<UserContext>(userContextKey, {
id: "anonymous",
name: "Anonymous",
})
const user = useStore(store)
return <span>{user.name}</span>
}API
getServerContextAtom<T>(key, defaultValue?)
Creates or reads a server-only atom for the current RSC request. Passing defaultValue seeds the
value for that key. Reading the same key later in the same request returns the same atom value,
while concurrent requests stay isolated from each other.
const theme = getServerContextAtom("theme", "dark")
theme.value = "light"AtomContextProvider
A client component that writes a server value into the matching client atom and keeps it in sync
when serverValue changes.
<AtomContextProvider contextKey="theme" serverValue="dark">
{children}
</AtomContextProvider>getClientContextAtom<T>(key, initial)
Returns the client-side Nanostores WritableAtom instance for a key. The same key always returns
the same atom instance. Use store.get(), store.set(value), and store.subscribe(listener)
directly, or connect it to React with useStore from @nanostores/react.
Notes
- Use stable, unique keys to avoid collisions between unrelated values.
- Import
getServerContextAtomonly from Server Components, server utilities, or files that already run under the React server condition. - Values are not reactive inside an already-rendered Server Component. If you mutate
.value, read it again from the atom when you need the latest value.
Acknowledgement
The server-side atom approach was inspired by Jonathan Gamble's article Easy Context in React Server Components (RSC).