Client SDK

The trellis/client package provides an SDK for interacting with your Trellis graph from an external process or across a network. It is fully isomorphic, working seamlessly in Node.js, Bun, and browser environments.

TrellisClient

The main class used to connect to a workspace and execute transactions or queries.

import { TrellisClient } from "trellis/client";

const client = new TrellisClient({
  url: "ws://localhost:3000",
  apiKey: "your-api-key",
});

// Connect mapping
await client.connect();

// Run a one-off query
const issues = await client.query('find issue.status="open"');

// Subscribe to a live query
const unsub = client.subscribe('find issue.status="open"', (results) => {
  console.log("Issues updated:", results);
});

Live reads (3.2.0)

For typed, hydrated subscriptions on persisted graph data, use liveEntities and liveEntity. They wrap the remote WebSocket subscription layer and work with or without a defineType schema handle.

import { liveEntities, liveEntity } from "trellis/client";
import { TrellisDb } from "trellis/client/sdk";

import { NavSection } from "./schema";

const client = new TrellisDb({ url: "http://localhost:8230" });

const list = liveEntities(client, NavSection, { resolve: { items: true } });
list.start();

const one = liveEntity(client, NavSection, "nav-section:abc");
one.start();

Remote mode only today. Local embedded-kernel live reads are planned; subscribe() in local mode surfaces an error state instead of throwing.

Prefer framework hooks (trellis/vue/typed, etc.) in UI code. See Typed SDK guide and Schema API.

config

Config types and constants shared between the server and the client to dictate limits, feature flags, and defaults.