TinyBase is a small reactive data store for local-first apps. Its MergeableStore can sync between clients through a WebSocket server that you run in Node.js. Until now, that server trusted every client equally: anyone who could connect to a path could write anything. TinyBase v10.1, published to npm on 12 November 2026, changes that. createWsServer now accepts authorize, canWriteCell and canWriteValue functions, so the server decides who may join and what each client may change. This tutorial builds a small role-based sync server in Node.js. The example code was tested with [email protected] and ws.

What v10.1 adds

From the official release notes:

  • authorize(pathId, request) receives the HTTP request that opened the WebSocket. It returns a ClientAccess object, optionally read-only and carrying a context, or undefined to refuse the client. It can also be async.
  • canWriteCell(...) / canWriteValue(...) run for every incoming change. Changes they reject are neither merged nor passed on to other clients.
  • Self-healing clients: if a refused change was newer than the server’s data, the server sends that client the server’s version, so the client doesn’t quietly drift.
  • Server as the only peer: once a server authorizes clients, each path’s MergeableStore becomes the single peer clients sync with, because clients can no longer be trusted to answer each other.
  • Cheaper sync: the release notes give an example where a client reconnecting to a 10,000-row table with one changed row exchanges about 8 kB instead of about 620 kB.
  • maxBufferSize: the largest message size, previously fixed at 16 MiB, can now be configured.

Client code needs no changes.

Step 1: Install

npm install tinybase@^10.1.0 ws

Use Node.js with ES modules ("type": "module" in package.json, or .mjs files).

Step 2: A server with roles

In this example, staff can edit anything, while viewers may only add to a comments table. Clients send a token in the query string. In a real app you would verify a signed session token or JWT instead of using a lookup table.

// server.mjs
import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';
import {WebSocketServer} from 'ws';

const TOKENS = {'staff-token': 'staff', 'viewer-token': 'viewer'}; // demo only

const roleFrom = (request) => {
  const token = new URL(request.url, 'http://localhost').searchParams.get('token');
  return TOKENS[token];
};

export const server = createWsServer(new WebSocketServer({port: 8060}), {
  authorize: (pathId, request) => {
    const role = roleFrom(request);
    if (!role) return undefined;          // refuse unknown clients
    return {context: {role}};             // context is passed to canWrite* below
  },
  canWriteCell: (pathId, tableId, rowId, cellId, cell, {role}) =>
    role === 'staff' || tableId === 'comments',
});

The context object you return from authorize is passed as the last argument to canWriteCell and canWriteValue. It is the natural place to keep a user ID, tenant ID or role.

Step 3: Two clients, one forbidden write

// demo.mjs
import {createMergeableStore} from 'tinybase';
import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
import {WebSocket} from 'ws';
import {server} from './server.mjs';

const staff = createMergeableStore();
staff.setCell('prices', 'widget', 'amount', 10);
const s1 = await createWsSynchronizer(
  staff, new WebSocket('ws://localhost:8060/shop?token=staff-token'));
await s1.startSync();

const viewer = createMergeableStore();
const s2 = await createWsSynchronizer(
  viewer, new WebSocket('ws://localhost:8060/shop?token=viewer-token'));
await s2.startSync();

viewer.setCell('comments', 'c1', 'text', 'Nice!');   // allowed
viewer.setCell('prices', 'widget', 'amount', 1);     // not allowed

await new Promise((r) => setTimeout(r, 1500));
console.log('viewer', JSON.stringify(viewer.getTables()));
console.log('staff ', JSON.stringify(staff.getTables()));

await s1.destroy(); await s2.destroy(); await server.destroy();

Running it printed:

viewer {"prices":{"widget":{"amount":10}},"comments":{"c1":{"text":"Nice!"}}}
staff  {"prices":{"widget":{"amount":10}},"comments":{"c1":{"text":"Nice!"}}}

The viewer’s comment reached staff. The viewer’s attempt to set the price to 1 was rejected, and the server pushed the correct value (10) back to the viewer. Nothing changed on the server or for other clients.

Step 4: Read-only clients

For dashboards or public displays, you don’t need cell-level rules. Mark the client read-only:

authorize: (pathId, request) =>
  roleFrom(request) === 'display' ? {readOnly: true} : {context: {role: roleFrom(request)}},

A read-only client still receives every update on the path but can’t write.

Step 5: Async checks and multi-tenant paths

authorize may return a Promise, so you can check a database or an auth service. canWriteCell and canWriteValue must be synchronous, because they run for every change. Do the slow work once in authorize and put the result in context:

authorize: async (pathId, request) => {
  const user = await verifySessionToken(request);         // your auth code
  if (!user) return undefined;
  if (!(await userCanOpenPath(user.id, pathId))) return undefined;
  return {context: {userId: user.id, role: user.role}};
},
canWriteCell: (pathId, tableId, rowId, cellId, cell, {userId, role}) =>
  role === 'admin' || (tableId === 'notes' && rowId.startsWith(`${userId}:`)),

pathId comes from the WebSocket URL path (/shop, /tenant-42, and so on), so it maps naturally to tenants or documents. Also note that deletions reach canWriteCell with cell set to undefined. If users may edit but not delete, check for that case.

Step 6: Large stores and safety limits

If a new client must receive a very large path in one message, raise maxBufferSize on the server and set the matching new last parameter of createWsSynchronizer on clients. The release notes also say an authorizing server refuses clients whose ID is unusable or already in use on the path, and limits how much one WebSocket can hold or have waiting for authorization. These are useful defaults against abusive clients.

Things to check when upgrading

  • Your proxy rules still matter. Authorization lives in the TinyBase server now, but keep TLS and origin checks at your proxy.
  • Peer-to-peer behaviour changes once you authorize. Clients sync only with the server’s store for that path.
  • Database persisters: persister-postgres now needs Postgres.js v4 or later, and schematizer-effect needs Effect v4 or later. Check your own direct use of those libraries, for example sql.array() was removed in Postgres.js v4.
  • Durable Objects: WsServerDurableObject has the same features as overridable authorize, canWriteCell and canWriteValue methods.

Takeaway

TinyBase v10.1 makes it realistic to put a local-first sync server on the public internet with Node.js. Authenticate once in authorize, pass the user in context, and keep canWriteCell and canWriteValue fast and synchronous. Rejected writes heal themselves on the client, and sync traffic drops a lot. Read more in the TinyBase releases guide and the createWsServer API docs.