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
| Part | React | Solid | Svelte |
|---|---|---|---|
| Committed actor state | useActorState(handle) | createActorState(handle) | actorState(handle) |
| A live query | useLiveQuery({ query, input }) | createLiveQuery({ query, input }) | liveQuery({ query, input }) |
| A command with pending and failure state | useCommand({ handle, name }) | createCommand({ handle, name }) | command({ handle, name }) |
| Channel presence and events | useChannel({ 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
| Part | React | Solid | Svelte |
|---|---|---|---|
| Committed actor state | useActorState(handle) | createActorState(handle) | actorState(handle) |
| A live query | useLiveQuery({ query, input }) | createLiveQuery({ query, input }) | liveQuery({ query, input }) |
| A command with pending and failure state | useCommand({ handle, name }) | createCommand({ handle, name }) | command({ handle, name }) |
| Channel presence and events | useChannel({ 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 }orFailed { failure }. Thevalueof a live actor state is the descriptor’s state union. - Channel state: a channel is
Connecting,Connected { connection, events, members }orFailed { 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:
runresolves toSucceeded { output }orRejected { failure }and never rejects. The runner also exposespendingand an optionalfailurethat 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:
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: [],
})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:
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.