Skip to content

Tutorial: ReactJS Todo

Note Full source code: vski.sh/x/template_frontend

VSKI is not only a backend for services and agents: the same API serves browser frontends directly. This tutorial builds a multi-user todo application in React (Vite + TypeScript) where accounts, per-user data and live synchronization all come from the platform:

  • sign up and sign in against the system _users auth collection
  • each user sees and edits only their own todos, enforced by the database, not by the client
  • a todo checked in one browser tab appears checked in another tab (and in another browser) instantly, over a WebSocket

No custom backend is written: the whole server side is one collection with rules, declared as code.

flowchart LR
R["React app<br/>Vite + TS<br/>@vski/sdk"] <-->|"REST (records, auth)"| V["VSKI server<br/>SQLite + FTS, rules engine"]
R <-->|"WebSocket (realtime)"| V

One page, one collection, five rules. The interesting parts are not the React code, but what the app does not have to do: authentication storage, per-user filtering, change notification, reconnection logic.

  • A running VSKI server with the first admin created (see Getting Started)
  • Node.js 20 or newer
  • The vski CLI for the IaC step (see SDKs and CLI)

Accounts need no declaration: every database ships with a system _users auth collection, and registration and login go through /api/auth/*. What we declare is the todos collection and who may touch a record:

vski/default/collections.yaml
version: 1
database: default
collections:
todos:
type: base
fields:
- {name: text, type: text, required: true}
- {name: done, type: bool}
- {name: authorId, type: text, required: true}
rules:
list: "authorId = @request.auth.id"
view: "authorId = @request.auth.id"
create: "authorId = @request.auth.id"
update: "authorId = @request.auth.id"
delete: "authorId = @request.auth.id"

Every rule is the same expression (see Rules and Access Control): @request.auth.id resolves to the id of the authenticated user, so:

  • list and view filter queries to records the caller authored; another user’s todos are not hidden, they are simply not returned
  • create rejects a record whose authorId is not the caller, so a logged-in user cannot write todos into someone else’s list
  • update and delete apply the same check to existing records

Apply it:

Terminal window
pip install --extra-index-url https://vski.sh/api/packages/x/pypi/simple/ "vski-sdk[cli]"
export VSKI_URL=http://127.0.0.1:3000
vski login # admin email + password
vski iac apply vski
Terminal window
npm create vite@latest vski-todos -- --template react-ts
cd vski-todos
npm install @vski/sdk

The SDK is served by the vski.sh npm registry, so tell npm about the scope in .npmrc (reads are public, no credentials needed):

.npmrc
@vski:registry=https://vski.sh/api/packages/x/npm/

The server URL comes from the environment, with a local default:

.env.local
VITE_VSKI_URL=http://127.0.0.1:3000

If your server runs with ALLOWED_ORIGINS, add the dev origin (http://127.0.0.1:5173) to it; realtime WebSockets need it too.

One VskiClient instance for the whole app. The JWT and the user record survive reloads in localStorage; on boot the app revalidates the token:

src/lib/sdk.tsx
import { VskiClient } from "@vski/sdk";
const url = import.meta.env.VITE_VSKI_URL || "http://127.0.0.1:3000";
const client = new VskiClient(url);
// restore a previous session
const token = localStorage.getItem("todos_token");
if (token) client.setToken(token);

Registration and login are one call each; login also sets the client token, and both return the user record:

// create an account, then sign in with it
await client.auth.register({
email,
password,
passwordConfirm: password,
name: email.split("@")[0],
});
const res = await client.auth.login(email, password);
localStorage.setItem("todos_token", res.token);
// res.user: {id, email, ...}
// later, on reload: is the token still good?
const me = await client.auth.me();

The initial state is a regular query. Records come back newest first:

const page = await client.collection<Todo>("todos").getList({
page: 1,
perPage: 200,
sort: "-created",
});
setTodos(page.items);

Note there is no where authorId = me anywhere: the list rule already filtered the result on the server.

After the initial load the app subscribes to the collection, and every create, update and delete arrives as an event:

useEffect(() => {
if (!user) return;
const unsub = client.collection<Todo>("todos").subscribe((event) => {
// event.action: "create" | "update" | "delete"
// event.record: the changed record
if (event.action === "delete") {
setTodos((prev) => prev.filter((t) => t.id !== event.record.id));
return;
}
if (event.record.authorId !== user.id) return; // see below
setTodos((prev) => upsert(prev, event.record));
});
return unsub; // unsubscribe on unmount / sign out
}, [user]);

Two things worth understanding:

  • The server filters events per subscriber. The collection’s list rule applies at subscribe time and again to every delivered event: with list: "authorId = @request.auth.id" the server evaluates each event’s record against the subscriber before sending it, so user B’s records never reach user A’s socket (and a closed collection rejects the subscription outright). The event.record.authorId !== user.id check above still has value as defense in depth: it costs one line and guards the UI even if the collection’s rules are later loosened on the server.
  • Events reconcile, they do not command. Mutations below apply the server response immediately for a snappy UI; when the matching event arrives a moment later, upserting by id is a no-op. That is what makes two tabs converge on the same state.

The SDK manages the WebSocket itself: it connects on the first subscribe, reconnects after a drop, and resends the subscriptions after reconnecting (see Realtime).

Each action is a single client call; the todo is a record, nothing more:

const todos = client.collection<Todo>("todos");
// add
const created = await todos.create({
text,
done: false,
authorId: user.id, // must be ours: the create rule checks it
});
// check off
await todos.update(created.id, { done: true });
// remove one
await todos.delete(created.id);
// remove all completed at once
await todos.bulkDelete(doneIds);

A user who tries to create a todo with someone else’s authorId gets a plain HTTP 403 from the rule engine; surfacing that error in the UI is all the client has to do about security.

Terminal window
npm run dev # http://127.0.0.1:5173
  1. Create an account, add a few todos
  2. Open the same URL in a second tab: the list is already there
  3. Check a todo in one tab and watch it flip in the other, without a reload
  4. Sign up as a second user in a private window: the list is empty, and no amount of trying will make the first user’s todos appear

For production, npm run build produces a fully static dist/: host it on any static server or CDN, keep the origin in ALLOWED_ORIGINS, and point VITE_VSKI_URL at the deployment’s server.

ConcernWho handles itWhere it is declared
Accounts, hashingthe platformsystem _users collection
Per-user isolationthe rules enginerules: in collections.yaml
Change notifyingthe realtime enginesubscribe(...) in the app
Reconnectingthe SDKautomatic
Persistenceper-tenant SQLitethe server’s data dir

The application code is left with what it should be left with: rendering, draft input, and the optimistic UI.

  • Realtime: consumer groups, metrics and the event stream
  • Rules and Access Control: field-level rules and role checks
  • SDKs: installing the TypeScript and Python SDKs
  • Pipelines: react to collection events server side, for example to index or enrich todos as they are created