@sh1n4ps/plasma-react

React hooks for plasma. Wraps a PlasmaClient so components can subscribe to live queries and fire optimistic mutations without touching the sync loop directly.

Install

pnpm add @sh1n4ps/plasma-react @sh1n4ps/plasma-client @sh1n4ps/plasma-core react

Requires react >= 18.

Quick shape

import { PlasmaProvider, useLiveQuery, useMutation } from "@sh1n4ps/plasma-react"
import { plasma } from "./client"           // createPlasmaClient(...)
import { mutators, todos } from "./schema"  // shared with the worker

function TodoList() {
  const rows = useLiveQuery<Todo>(
    () => plasma.db.select().from(todos),
    [],
  )
  const create = useMutation<typeof mutators, "createTodo">("createTodo")

  return (
    <>
      <button
        disabled={create.isPending}
        onClick={() => create.mutate({
          id: plasma.newId(),
          title: "buy milk",
          updatedAt: Date.now(),
        })}
      >
        add
      </button>
      <ul>{rows.map(r => <li key={r.id}>{r.title}</li>)}</ul>
    </>
  )
}

export function App() {
  return (
    <PlasmaProvider client={plasma}>
      <TodoList />
    </PlasmaProvider>
  )
}

What lives here

• PlasmaProvider — puts the client on React context.
• usePlasma — grabs the client from context; throws when a caller forgets the provider.
• useLiveQuery(queryFactory, deps) — subscribes to .live() under the hood. queryFactory is re-evaluated when deps change (same ergonomics as useMemo). Initial render returns []; the first live delivery lands after the async engine settles.
• useMutation(name) — wraps client.mutate(name, args) with isPending / error / reset state so buttons and forms compose naturally.

Design notes

The context erases the client's generic parameters; the hooks reinstate them via explicit type arguments at the call site. This is deliberate: apps typically instantiate a single client and only see it through a concrete typeof mutators narrowing, which keeps the provider itself free of app-specific types.