Skip to content
Vaultbase

SDK quick start

The official TypeScript SDK ships at @vaultbase/sdk. One client object exposes auth, records, files, realtime, batch, flags, and custom routes.

Install

Section titled “Install”
Terminal window
bun add @vaultbase/sdk
# or
npm install @vaultbase/sdk

Works in Bun, Node 20+, Deno, Cloudflare Workers, and the browser.

Hello, Vaultbase

Section titled “Hello, Vaultbase”
import { Vaultbase } from "@vaultbase/sdk";


const vb = new Vaultbase({ baseUrl: "https://api.example.com" });


// Records
const post = await vb.collection("posts").create({ title: "hi" });
const list = await vb.collection("posts").list({ filter: "published = true" });


// Auth
await vb.auth.users.login({ email: "a@b.c", password: "•••" });


// Realtime
const off = vb.subscribe("posts", "*", (ev) => console.log(ev.action, ev.record));
// off() to disconnect


// Files
const meta = await vb.files.upload("posts", post.id, "cover", file);


// Custom routes
const result = await vb.custom.get("/hello?name=world");

Constructor

Section titled “Constructor”
new Vaultbase({
  baseUrl: "https://api.example.com",      // required — your Vaultbase URL
  authStore: defaultAuthStore(),           // sessionStorage in browsers, memory in Node
  authTransport: "header",                 // "header" | "cookie" | "both" — default "both"
  withCredentials: false,                  // send cookies on cross-origin (CORS)
  defaultAutoCancel: true,                 // auto-abort prior request with same requestKey
  fetch: globalThis.fetch,                 // override for custom fetch wrappers
});

Auth stores

Section titled “Auth stores”

The SDK persists the auth token in a pluggable store.

StoreWhere the token livesWhen to use
MemoryAuthStoreRAM onlyTests, server-rendering, short-lived workers
SessionStorageAuthStoresessionStorageBrowser SPA — cleared on tab close (default)
LocalStorageAuthStorelocalStorageBrowser SPA persisting across tabs (less safe)
CookieAuthStoredocument.cookieWhen you also want the server’s HttpOnly cookie to be the source of truth
import { Vaultbase, MemoryAuthStore } from "@vaultbase/sdk";


const vb = new Vaultbase({
  baseUrl: "https://api.example.com",
  authStore: new MemoryAuthStore(),
});

Typed schema (codegen)

Section titled “Typed schema (codegen)”

Run vb-types against a live admin to generate a Schema from your collections. Pass it to the Vaultbase generic and every collection / filter / record becomes typed end-to-end. See Codegen + migrate CLI.

import type { Schema } from "./vaultbase.gen";
const vb = new Vaultbase<Schema>({ baseUrl: "..." });


const post = await vb.collection("posts").create({
  title: "hi",       // ✓ typed
  publishedAt: "x",  // ✗ TS error if 'publishedAt' isn't on Post['create']
});

API versioning

Section titled “API versioning”

The SDK targets /api/v1/. Future breaking changes ship as /api/v2/ and you opt in with vb.useApiVersion("v2") once available. See API versioning.

Where next

Section titled “Where next”