@supalive/react

React bindings for supalive — reactive queries for any Postgres/MySQL.

Installation

npm install @supalive/react @supalive/core

Quick start

1. Create a typed client

// supalive.tsx
import {
  createSupaliveContext,
  createSupaliveProvider,
  createUseSupalive,
  createUseConnectionState,
  createLiveQuery,
  createQuery,
  createMutation,
  createAction,
} from "@supalive/react";
import type { AppRouter } from "./procedures";

export const SupaliveContext = createSupaliveContext<AppRouter>();

export const SupaliveProvider = createSupaliveProvider(SupaliveContext);

export const useSupalive = createUseSupalive(SupaliveContext);
export const useConnectionState = createUseConnectionState(SupaliveContext);
export const useLiveQuery = createLiveQuery(SupaliveContext);
export const useQuery = createQuery(SupaliveContext);
export const useMutation = createMutation(SupaliveContext);
export const useAction = createAction(SupaliveContext);

2. Wrap your app

// App.tsx
import { SupaliveProvider } from "./supalive";

export default function App() {
  return (
    <SupaliveProvider
      url="ws://localhost:3000"
      token={getAuthToken()}
    >
      <Todos />
    </SupaliveProvider>
  );
}

3. Use live queries and mutations

// Todos.tsx
import { useLiveQuery, useMutation } from "./supalive";

function Todos() {
  const { data, status } = useLiveQuery((c) => c.listItems, { status: "todo" });
  const [createItem] = useMutation((c) => c.createItem);

  return (
    <>
      {data?.map((item) => <li key={item.id}>{item.title}</li>)}
      <button onClick={() => createItem({ id: crypto.randomUUID(), title: "new", status: "todo" })}>
        add
      </button>
    </>
  );
}

API

| Hook | Description | |------|-------------| | useLiveQuery(c => c.proc, args) | Subscribe to live results; re-renders on push | | useQuery(c => c.proc, args) | One-shot query | | useMutation(c => c.proc) | Returns [mutate, { status }] | | useAction(c => c.proc) | Returns [run, { status }] | | useSupaliveConnectionState() | connecting \| connected \| reconnecting \| closed |

The hooks are factory-built so you get fully-typed autocomplete on c.<procedure> from your own router type.

Requirements

• React 18+
• A running supalive server (see @supalive/core)

License

MIT