No description
  • TypeScript 79.8%
  • CSS 12.2%
  • Makefile 5.3%
  • HTML 2.7%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-03 00:02:33 +01:00
src first commit 2026-11-02 23:28:46 +01:00
vski/default first commit 2026-11-02 23:28:46 +01:00
.env.example first commit 2026-11-02 23:28:46 +01:00
.gitignore first commit 2026-11-02 23:28:46 +01:00
.npmrc first commit 2026-11-02 23:28:46 +01:00
index.html first commit 2026-11-02 23:28:46 +01:00
Makefile first commit 2026-11-02 23:28:46 +01:00
package-lock.json first commit 2026-11-02 23:28:46 +01:00
package.json first commit 2026-11-02 23:28:46 +01:00
README.md fix readme 2026-11-03 00:02:33 +01:00
tsconfig.json first commit 2026-11-02 23:28:46 +01:00
tsconfig.tsbuildinfo first commit 2026-11-02 23:28:46 +01:00
vite.config.ts first commit 2026-11-02 23:28:46 +01:00

VSKI Frontend Template: React Todo

A Vite + React + TypeScript app on VSKI: accounts, per-user data, and realtime sync across tabs and devices, with no backend code. The whole server side is two declarative collections in vski/default/collections.yaml.

What it demonstrates:

  • Email/password auth through the SDK (client.auth.register/login/me), stored in an _users auth collection.
  • Per-user records with rules: every todos rule is authorId = @request.auth.id, so the database itself enforces that a user only ever reads and writes their own todos.
  • Realtime: collection("todos").subscribe(...) receives every create/update/delete over a WebSocket, so a todo checked in one tab appears checked in another (open two browser tabs and try it).
  • IaC: collections, fields and rules are declared in vski/ and applied with vski iac apply.

Prerequisites

  • A running VSKI server (see the platform Getting Started): vski install && vski serve, then create the first admin at http://127.0.0.1:3000/installer.
  • Node.js 20+ and a Python 3.11+ for the vski CLI.

Setup

# 1. dependencies (npm reads .npmrc: @vski comes from the vski.sh registry)
npm install

# 2. the server side: _users + todos collections, applied declaratively
make venv                      # vski CLI in .venv
make iac-apply VSKI_URL=http://127.0.0.1:3000   # or: vski login first

# 3. the app
cp .env.example .env.local     # point VITE_VSKI_URL at your server
npm run dev                    # http://127.0.0.1:5173

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

Sign up with any email/password (min 8 chars), add todos, then open the same URL in a second tab or another browser and watch the list stay in sync.

Layout

.
├── .npmrc                    # @vski scope -> vski.sh npm registry
├── .env.example              # VITE_VSKI_URL
├── Makefile                  # deps, dev, build, iac-plan/apply/pull
├── vski/
│   └── default/
│       └── collections.yaml  # _users (auth) + todos (owner-only rules)
└── src/
    ├── lib/sdk.tsx           # one VskiClient, JWT session in localStorage
    ├── components/
    │   ├── Header.tsx        # brand, live indicator, theme, sign out
    │   ├── AuthPanel.tsx     # register / sign in
    │   └── TodoApp.tsx       # CRUD + realtime reconciliation + filters
    └── globals.css           # the platform design system (Tailwind + DaisyUI)

How realtime works here

After the initial getList, the app subscribes to the collection:

client.collection<Todo>("todos").subscribe((event) => {
  // event.action: "create" | "update" | "delete"
  // event.record: the changed record
});

Subscriptions are per collection, not per record, but the server filters delivery: the collection's list rule (authorId = @request.auth.id here) is evaluated per subscriber and per event, so another user's records never arrive on this socket in the first place. The app still checks record.authorId against the signed-in user as defense in depth, in case the server-side rules are ever loosened. Mutations apply the server response immediately and the arriving event reconciles the same record idempotently.

Production build

npm run build     # static bundle in dist/, serve it from anywhere

dist/ is fully static: host it on any static server/CDN behind the VSKI API. Keep the origin in the server's ALLOWED_ORIGINS.

Reference