@archlast/client

The Archlast client SDK provides WebSocket-based queries and mutations, React hooks with cache integration, authentication helpers, storage utilities, admin APIs, and optional tRPC access.

Installation

npm install @archlast/client

# Other package managers
pnpm add @archlast/client
yarn add @archlast/client
bun add @archlast/client

Peer dependencies:

npm install react react-dom @tanstack/react-query

Quick start

import { ArchlastClient } from "@archlast/client";
import { ArchlastProvider, useQuery, useMutation } from "@archlast/client/react";
import { api } from "./_generated/api";

const client = new ArchlastClient(
  "ws://localhost:4000/ws",
  "http://localhost:4000",
  "web"
);

function App() {
  return (
    <ArchlastProvider client={client}>
      <TodoList />
    </ArchlastProvider>
  );
}

function TodoList() {
  const tasks = useQuery(api.tasks.list, {});
  const createTask = useMutation(api.tasks.create);

  return (
    <div>
      <pre>{JSON.stringify(tasks, null, 2)}</pre>
      <button onClick={() => createTask({ text: "New task" })}>
        Add
      </button>
    </div>
  );
}

The api object is generated by the CLI in _generated/api.ts.

Client configuration

Constructor signature:

new ArchlastClient(wsUrl, httpUrl?, appId?, authUrl?, options?)

Options:

• autoConnect (default true)
• apiKey Better Auth API key (arch_ prefix)
• isAdmin subscribe to admin streams
• betterAuthCookies for session cookies

const client = new ArchlastClient(
  "ws://localhost:4000/ws",
  "http://localhost:4000",
  "web",
  undefined,
  { apiKey: "arch_example" }
);

client.setApiKey("arch_new_key");
client.setBetterAuthCookies({ "better-auth.session": "..." });

React hooks

Available from @archlast/client/react:

• useQuery / useMutation for live queries and mutations
• usePagination for cursor based queries
• useAuth for Better Auth session state
• useUpload, useDownload for storage
• useStorageList, useStorageMetadata, useStorageDeleteFile

Example:

const items = useQuery(api.items.list, { limit: 10 });
const createItem = useMutation(api.items.create);

Direct client usage

const data = await client.fetch("tasks.get", { id: "123" });
const updated = await client.mutate("tasks.update", { id: "123", text: "Hi" });

Authentication

Auth uses Better Auth endpoints under /api/auth/*.

import { useAuth } from "@archlast/client/react";

const { signIn, signOut, isAuthenticated } = useAuth();

Or use the auth client directly:

import { ArchlastAuthClient } from "@archlast/client/auth";

const auth = new ArchlastAuthClient({ baseUrl: "http://localhost:4000" });

Storage

const file = new File(["hello"], "hello.txt", { type: "text/plain" });
const uploaded = await client.storage.upload(file);
const list = await client.storage.list();
const { url } = await client.storage.presign(uploaded.id);

Admin APIs

const profile = await client.admin.auth.getProfile();

tRPC integration

import { createArchlastTRPCClient } from "@archlast/client/trpc";
import type { AppRouter } from "./_generated/rpc";

const trpc = createArchlastTRPCClient<AppRouter>({
  baseUrl: "http://localhost:4000",
  apiKey: "arch_example"
});

Subpath exports

• @archlast/client/react
• @archlast/client/trpc
• @archlast/client/auth
• @archlast/client/storage
• @archlast/client/admin

Troubleshooting

• WebSocket errors: use ws://<host>/ws and confirm CORS settings.
• Auth errors: ensure cookies or API key are configured.
• Storage uploads: use File or Blob for browser uploads.

Publishing (maintainers)

See docs/npm-publishing.md for release and publish steps.