@synap-core/react

React hooks and provider for Synap data pods. Built on TanStack Query + tRPC for real-time, type-safe data fetching.

Install

npm install @synap-core/react
# or
pnpm add @synap-core/react

Quick start

1. Wrap your app

import { SynapProvider } from "@synap-core/react";

export default function App() {
  return (
    <SynapProvider
      podUrl="https://your-pod.synap.live"
      apiKey="sk_live_..." // from Workspace → Settings → API Keys
      workspaceId="ws_..."
    >
      <YourApp />
    </SynapProvider>
  );
}

2. Use hooks anywhere inside

import { useSynap } from "@synap-core/react";

function EntityList() {
  const { data, isLoading } = useSynap().entities.list.useQuery({ limit: 20 });

  if (isLoading) return <p>Loading...</p>;

  return (
    <ul>
      {data?.items.map((entity) => (
        <li key={entity.id}>{entity.title}</li>
      ))}
    </ul>
  );
}

function CreateNote() {
  const create = useSynap().entities.create.useMutation();

  return (
    <button
      onClick={() =>
        create.mutate({
          profileSlug: "note",
          title: "New note",
          properties: { content: "Hello!" },
        })
      }
    >
      Create note
    </button>
  );
}

API

<SynapProvider>

| Prop | Type | Required | Description | | -------------- | ------------------------ | -------- | ---------------------------------------- | | podUrl | string | ✓ | Data pod base URL (no trailing slash) | | workspaceId | string | ✓ | Workspace ID | | apiKey | string | — | Bearer token. Omit for cookie-based auth | | extraHeaders | Record<string, string> | — | Extra request headers | | queryClient | QueryClient | — | Reuse an existing TanStack Query client |

useSynap()

Returns the full tRPC hook tree. Every procedure is available:

// Queries
useSynap().entities.list.useQuery(input);
useSynap().workspaces.get.useQuery();
useSynap().channels.list.useQuery({ workspaceId });

// Mutations
useSynap().entities.create.useMutation();
useSynap().entities.update.useMutation();
useSynap().chat.sendMessage.useMutation();

useSynapContext()

Access the current pod URL and workspace ID inside a provider:

const { podUrl, workspaceId } = useSynapContext();

Ergonomic data hooks

Thin, fully-typed wrappers over the most common reads — no need to remember procedure paths. They are plain TanStack-Query hooks (accept enabled, staleTime, etc. as a second argument):

import { useEntity, useEntities, useLinks, useView } from "@synap-core/react";

function Profile({ id }: { id: string }) {
  const { data: entity } = useEntity(id);                    // entities.get
  const { data: links } = useLinks(id);                      // relations.get (both directions)
  return <h1>{entity?.entity?.title}</h1>;
}

function People() {
  const { data } = useEntities("person", { limit: 50 });     // entities.list
  return <ul>{data?.items.map((e) => <li key={e.id}>{e.title}</li>)}</ul>;
}

function MyView({ viewId }: { viewId: string }) {
  const { data: view } = useView(viewId);                    // views.get
  return <pre>{JSON.stringify(view, null, 2)}</pre>;
}

| Hook | Procedure | Notes | | ----------------------------- | --------------- | --------------------------------------- | | useEntity(id, opts?) | entities.get | opts.includeProfile?: boolean | | useEntities(slug?, opts?) | entities.list | opts: { workspaceId?, projectId?, limit? } | | useLinks(entityId, opts?) | relations.get | opts.direction?: "source" \| "target" \| "both" (default both) | | useView(viewId, opts?) | views.get | — |

For anything else, drop down to useSynap() (the full tRPC tree).

Type helpers

import type { RouterInputs, RouterOutputs } from "@synap-core/react";

type CreateEntityInput = RouterInputs["entities"]["create"];
type EntityListOutput = RouterOutputs["entities"]["list"];

Vanilla JS

For non-React apps use @synap-core/sdk directly.

API reference

Full procedure reference: docs.synap.live/reference/api-reference