Skip to main content

Client SDK Overview

Client SDK Overview

The nodestack-client is a zero-dependency, isomorphic TypeScript & JavaScript client for NodeStack. It runs seamlessly in web browsers, React, Next.js, React Native, Node.js, Bun, and Deno.


Highlights​

Ultra-lightweight: < 10 KB minified + gzipped. Multi-Application Scoping: Fluent client.app(slug) scoping, automatic x-nodestack-app header injection, and client.apps management service. Reactive Auth: LocalAuthStore (browser localStorage), MemoryAuthStore (Node/SSR/testing), with onChange subscriptions. Fluent CRUD Operations: getList, getFullList, getFirstListItem, create, update, delete. Application Snapshots: Programmatic checkpoint management with client.snapshots (create, restore, drift checks, FIFO eviction). FTS5 Full-Text Search: Built-in support for BM25 ranking, prefix queries, and highlighted snippet excerpts. Webhooks Client Service: Webhook registration, delivery logs, test dispatch, and HMAC verification. Multiplexed SSE Realtime: Persistent connection with auto-handshake and auto-reconnect. 100% Type-Safe: Works with nodestack typegen for complete end-to-end typing.


Installation​

npm install nodestack-client

Initializing the Client​

In the Browser (React / Vue / Svelte / Plain JS)​

import NodeStackClient from 'nodestack-client';

// Connects to your backend and persists auth in localStorage
const client = new NodeStackClient('http://localhost:8090');

In Node.js / Server-Side Rendering (Next.js / Remix / SSR)​

In server environments without window.localStorage, pass a MemoryAuthStore:

import NodeStackClient, { MemoryAuthStore } from 'nodestack-client';

const client = new NodeStackClient('http://localhost:8090', {
authStore: new MemoryAuthStore(),
});

Reactive Auth State Listener​

Listen to login and logout events across your entire application:

client.authStore.onChange((token, record) => {
console.log('User auth state changed:');
console.log('Token exists:', !!token);
console.log('Active user ID:', record?.id);
});

Multi-Application Scoping​

When connecting to a NodeStack server with multiple hosted applications, use client.app(slug) to scope all queries, file URLs, and realtime streams to a specific application:

// Create an app-scoped instance
const shopClient = client.app('shop');

// Automatically sends `x-nodestack-app: shop` header on all requests
const products = await shopClient.collection('products').getList(1, 10);

// File URLs automatically include the app prefix:
// /api/apps/shop/files/products/rec_123/image.png
const url = shopClient.files.getUrl(products.items[0], products.items[0].image);

// Realtime SSE automatically subscribes with ?app=shop
shopClient.collection('orders').subscribe('*', (e) => {
console.log('Shop order mutation:', e.record);
});

For more details on managing applications and architecture, see the Multi-Application Platform Guide.


Application Snapshots​

Manage time-travel checkpoints programmatically using client.snapshots:

// 1. Create a snapshot checkpoint
const snapshot = await client.snapshots.create({
label: 'Before Product Migration',
description: 'Schema backup prior to v2 product catalog update',
evictOldest: true, // Auto-evict oldest checkpoint if at 10-snapshot limit
});

// 2. List all snapshots and drift status
const list = await client.snapshots.list();
console.log('Active snapshots:', list.snapshots);
console.log('Database drift detected:', list.driftDetected);

// 3. Restore to checkpoint non-destructively
await client.snapshots.restore(snapshot.id);

For more details, see the Application Snapshots Guide.


Background Queues & Workers​

Produce and consume durable background queue messages with client.queue(name):

// Access a named queue
const emailQueue = client.queue('transactional-emails');

// 1. Enqueue a message with priority and partition group key
const message = await emailQueue.send({
to: 'alice@example.com',
subject: 'Order Confirmation',
orderId: 'ord_123'
}, {
groupKey: 'customer:cust_456', // Strict FIFO partition
priority: 10,
delaySeconds: 0
});

// 2. Claim and process messages in a worker loop
const jobs = await emailQueue.claim(5);
for (const job of jobs) {
try {
// Extend lease heartbeat if needed
await emailQueue.touch(job.id, job.claimToken);

// Complete job
await emailQueue.complete(job.id, { sent: true }, job.claimToken);
} catch (err: any) {
// Fail job and trigger automatic backoff retry or DLQ
await emailQueue.fail(job.id, err.message, job.claimToken);
}
}

For more details, see the Queues Overview and Workers & Functions guides.