Skip to content

UI bindings for React, Solid and Svelte

@akterjs/react, @akterjs/solid and @akterjs/svelte turn a @akterjs/sdk actor handle into reactive values. Each binding subscribes when a component mounts and stops when the component unmounts. The actor descriptor types every value, so a state union, a query reply and a command failure keep their types in the view.

Each package wraps the same four parts of a handle⁠

PartReactSolidSvelte
Committed actor stateuseActorState(handle)createActorState(handle)actorState(handle)
A live queryuseLiveQuery({ query, input })createLiveQuery({ query, input })liveQuery({ query, input })
A command with pending and failure stateuseCommand({ handle, name })createCommand({ handle, name })command({ handle, name })
Channel presence and eventsuseChannel({ channel, presence })createChannel({ channel, presence })channel({ channel, presence })

React returns plain values from hooks. Solid returns accessors. Svelte returns readable stores, so a component reads them with `# UI bindings for React, Solid and Svelte

@akterjs/react, @akterjs/solid and @akterjs/svelte turn a @akterjs/sdk actor handle into reactive values. Each binding subscribes when a component mounts and stops when the component unmounts. The actor descriptor types every value, so a state union, a query reply and a command failure keep their types in the view.

Each package wraps the same four parts of a handle⁠

PartReactSolidSvelte
Committed actor stateuseActorState(handle)createActorState(handle)actorState(handle)
A live queryuseLiveQuery({ query, input })createLiveQuery({ query, input })liveQuery({ query, input })
A command with pending and failure stateuseCommand({ handle, name })createCommand({ handle, name })command({ handle, name })
Channel presence and eventsuseChannel({ channel, presence })createChannel({ channel, presence })channel({ channel, presence })

and no compile step is needed in the package. A query without input omits input. A query with input resubscribes when the input changes by value.

run takes the command’s input and optional command options. To retry a run after ConnectionLostError without running the command twice, pass the same id each time, as in run({ reason: "archived" }, { commandId }).

A channel joins with the presence it has when the component mounts. To change presence later, call setPresence on the connection of the Connected state.

Live values are tagged unions⁠

  • Lifecycle: actor state and live queries are Loading, Live { value, version } or Failed { failure }. The value of a live actor state is the descriptor’s state union.
  • Channel state: a channel is Connecting, Connected { connection, events, members } or Failed { failure }. The members list starts from the welcome and follows every join, leave and presence change. The events list keeps the last 100 events.
  • Command outcome: run resolves to Succeeded { output } or Rejected { failure } and never rejects. The runner also exposes pending and an optional failure that holds the last rejection until the next run starts.

matchState from @akterjs/sdk matches every one of these unions, and the typecheck fails when a case is missing.

Show an actor in React⁠

The example renders one Board actor. The contract lives in the app, and the client side declares the same actor with Zod:

src/board.contract.ts
import { Schema } from "effect"
import { Akter } from "@akterjs/effect/contract"

export const Member = Akter.caller("user", Schema.Struct({ id: Akter.PrincipalId }))

export const Open = Schema.TaggedStruct("Open", { posts: Schema.Int, title: Schema.String })

export const Closed = Schema.TaggedStruct("Closed", { reason: Schema.String, title: Schema.String })

export const Board = Akter.make("Board", {
  callers: [Member],
  commands: {
    close: Akter.command({
      callers: [Member],
      errors: [],
      from: [Open],
      input: Schema.Struct({ reason: Schema.String }),
      output: Schema.Void,
      to: [Closed],
    }),
  },
  initial: { input: Schema.Struct({ title: Schema.String }), to: Open },
  key: Schema.String,
  parent: Akter.Root,
  queries: {},
  states: [Open, Closed],
  tables: [],
})
src/board-client.ts
import { Effect } from "effect"
import { z } from "zod"
import { recordedContracts } from "@akterjs/effect/contract/description"
import { actor, createClient } from "@akterjs/sdk"
import { Board } from "./board.contract.ts"

export const BoardActor = actor({
  commands: {
    close: { errors: {}, input: z.object({ reason: z.string() }), output: z.undefined() },
  },
  initial: z.object({ title: z.string() }),
  key: z.string(),
  name: "Board",
  queries: {},
  states: {
    Closed: z.object({ reason: z.string(), title: z.string() }),
    Open: z.object({ posts: z.int(), title: z.string() }),
  },
})

const contracts = await Effect.runPromise(recordedContracts([Board]))

export const client = createClient({ actors: [BoardActor], contracts, url: "http://localhost:5173" })

The url is the page’s own origin, a Vite dev server that proxies /rpc to the app. useActorState keeps the view on the committed state. useCommand runs close and reports whether a run is pending:

src/board-view.tsx
import { matchState } from "@akterjs/sdk"
import { useActorState, useCommand } from "@akterjs/react"
import { client } from "./board-client.ts"

export function BoardView({ boardKey }: { readonly boardKey: string }) {
  const board = client.Board(boardKey)
  const state = useActorState(board)
  const close = useCommand({ handle: board, name: "close" })

  const heading = matchState(state, {
    Failed: () => "Unavailable",
    Live: ({ value }) =>
      matchState(value, {
        Closed: ({ reason, title }) => `${title} (closed: ${reason})`,
        Open: ({ posts, title }) => `${title} (${posts} posts)`,
      }),
    Loading: () => "Loading",
  })

  return (
    <section>
      <h1>{heading}</h1>
      <button disabled={close.pending} onClick={() => void close.run({ reason: "archived" })}>
        Close
      </button>
    </section>
  )
}

Solid and Svelte code follows the same shape. In Solid, call state() to read the accessor. In Svelte, read $state from the store.

Install a binding⁠

To add React bindings to an application, run npm install @akterjs/react @akterjs/sdk @akterjs/client @akterjs/effect effect react.

To add Solid bindings, run npm install @akterjs/solid @akterjs/sdk @akterjs/client @akterjs/effect effect solid-js.

To add Svelte bindings, run npm install @akterjs/svelte @akterjs/sdk @akterjs/client @akterjs/effect effect svelte.

The page must reach the app on its own origin. Serve the page and the app from one origin shows a dev server proxy.