Todo app with shared workspaces

Let’s consider a fairly common application scenario: An app (in this case a todo app) with shared workspaces. For the sake of this guide, we’ll keep things simple but you should be able to nicely extend this to a more complex app.

Requirements

• There are multiple independent todo workspaces
• Each workspace is initially created by a single user
• Users can join the workspace by knowing the workspace id and get read and write access
• For simplicity, the user identity is chosen when the app initially starts (i.e. a username) but in a real app this would be handled by a proper auth setup

Data model

• We are splitting up our data model into two kinds of stores (with respective eventlogs and SQLite databases): The workspace store and the user store.

workspace store (one per workspace)

For the workspace store we have the following events:

• workspaceCreated
• todoAdded
• todoCompleted
• todoDeleted
• userJoined

And the following state model:

• workspace table (with a single row for the workspace itself)
• todo table (with one row per todo item)
• member table (with one row per user who has joined the workspace)

user store (one per user)

For the user store we have the following events:

• workspaceCreated
• workspaceJoined

And the following state model:

• user table (with a single row for the user itself)

Note that the workspaceCreated event is used both in the workspace and the user store. This is because each eventlog should be “self-sufficient” and not rely on other eventlogs to be present to fulfill its purpose.

Schemas

User store:

user.schema.ts

import { Events, makeSchema, Schema, State } from '@livestore/livestore'

// Emitted when this user creates a new workspace
const workspaceCreated = Events.synced({
  name: 'v1.WorkspaceCreated',
  schema: Schema.Struct({ workspaceId: Schema.String, name: Schema.String }),
})

// Emitted when this user joins an existing workspace
const workspaceJoined = Events.synced({
  name: 'v1.WorkspaceJoined',
  schema: Schema.Struct({ workspaceId: Schema.String, name: Schema.String }),
})

export const userEvents = { workspaceCreated, workspaceJoined }

// Table to store basic user info
// Contains only one row as this store is per-user.
const userTable = State.SQLite.table({
  name: 'user',
  columns: {
    // Assuming username is unique and used as the identifier
    username: State.SQLite.text({ primaryKey: true }),
  },
})

// Table to track which workspaces this user is part of
const userWorkspacesTable = State.SQLite.table({
  name: 'userWorkspaces',
  columns: {
    workspaceId: State.SQLite.text({ primaryKey: true }),
    name: State.SQLite.text(),
    // Could add role/permissions here later
  },
})

export const userTables = { user: userTable, userWorkspaces: userWorkspacesTable }

const materializers = State.SQLite.materializers(userEvents, {
  // When the user creates or joins a workspace, add it to their workspace table
  'v1.WorkspaceCreated': ({ workspaceId, name }) => userTables.userWorkspaces.insert({ workspaceId, name }),
  'v1.WorkspaceJoined': ({ workspaceId, name }) => userTables.userWorkspaces.insert({ workspaceId, name }),
})

const state = State.SQLite.makeState({ tables: userTables, materializers })

export const schema = makeSchema({ events: userEvents, state })

Workspace store:

workspace.schema.ts

import { Events, makeSchema, Schema, State } from '@livestore/livestore'

// Emitted when a new workspace is created (originates this store)
const workspaceCreated = Events.synced({
  name: 'v1.WorkspaceCreated',
  schema: Schema.Struct({
    workspaceId: Schema.String,
    name: Schema.String,
    createdByUsername: Schema.String,
  }),
})

// Emitted when a todo item is added to this workspace
const todoAdded = Events.synced({
  name: 'v1.TodoAdded',
  schema: Schema.Struct({ todoId: Schema.String, text: Schema.String }),
})

// Emitted when a todo item is marked as completed
const todoCompleted = Events.synced({
  name: 'v1.TodoCompleted',
  schema: Schema.Struct({ todoId: Schema.String }),
})

// Emitted when a todo item is deleted (soft delete)
const todoDeleted = Events.synced({
  name: 'v1.TodoDeleted',
  schema: Schema.Struct({
    todoId: Schema.String,
    deletedAt: Schema.DateFromString.check(Schema.isDateValid()),
  }),
})

// Emitted when a new user joins this workspace
const userJoined = Events.synced({
  name: 'v1.UserJoined',
  schema: Schema.Struct({ username: Schema.String }),
})

export const workspaceEvents = { workspaceCreated, todoAdded, todoCompleted, todoDeleted, userJoined }

// Table for the workspace itself (only one row as this store is per-workspace)
const workspaceTable = State.SQLite.table({
  name: 'workspace',
  columns: {
    workspaceId: State.SQLite.text({ primaryKey: true }),
    name: State.SQLite.text(),
    createdByUsername: State.SQLite.text(),
  },
})

// Table for the todo items in this workspace
const todosTable = State.SQLite.table({
  name: 'todos',
  columns: {
    todoId: State.SQLite.text({ primaryKey: true }),
    text: State.SQLite.text(),
    completed: State.SQLite.boolean({ default: false }),
    // Using soft delete by adding a deletedAt timestamp
    deletedAt: State.SQLite.integer({ nullable: true, schema: Schema.DateFromMillis }),
  },
})

// Table for members of this workspace
const membersTable = State.SQLite.table({
  name: 'members',
  columns: {
    username: State.SQLite.text({ primaryKey: true }),
    // Could add role/permissions here later
  },
})

export const workspaceTables = { workspace: workspaceTable, todos: todosTable, members: membersTable }

const materializers = State.SQLite.materializers(workspaceEvents, {
  'v1.WorkspaceCreated': ({ workspaceId, name, createdByUsername }) => [
    workspaceTables.workspace.insert({ workspaceId, name, createdByUsername }),
    // Add the creator as the first member
    workspaceTables.members.insert({ username: createdByUsername }),
  ],
  'v1.TodoAdded': ({ todoId, text }) => workspaceTables.todos.insert({ todoId, text }),
  'v1.TodoCompleted': ({ todoId }) => workspaceTables.todos.update({ completed: true }).where({ todoId }),
  'v1.TodoDeleted': ({ todoId, deletedAt }) => workspaceTables.todos.update({ deletedAt }).where({ todoId }),
  'v1.UserJoined': ({ username }) => workspaceTables.members.insert({ username }),
})

const state = State.SQLite.makeState({ tables: workspaceTables, materializers })

export const schema = makeSchema({ events: workspaceEvents, state })

Store configuration

Now that we’ve defined our schemas, let’s configure the stores:

Workspace store:

workspace.store.ts workspace.schema.ts

import { makePersistedAdapter } from '@livestore/adapter-web'
import sharedWorker from '@livestore/adapter-web/shared-worker?sharedworker'
import { storeOptions } from '@livestore/livestore'

import { schema } from './workspace.schema.ts'
import worker from './workspace.worker.ts?worker'

const adapter = makePersistedAdapter({
  storage: { type: 'opfs' },
  worker,
  sharedWorker,
})

// Define workspace store configuration
// Each workspace gets its own isolated store instance
export const workspaceStoreOptions = (workspaceId: string) =>
  storeOptions({
    storeId: `workspace-${workspaceId}`,
    schema,
    adapter,
    unusedCacheTime: 60_000, // Keep in memory for 60 seconds after last use
  })

import { Events, makeSchema, Schema, State } from '@livestore/livestore'

// Emitted when a new workspace is created (originates this store)
const workspaceCreated = Events.synced({
  name: 'v1.WorkspaceCreated',
  schema: Schema.Struct({
    workspaceId: Schema.String,
    name: Schema.String,
    createdByUsername: Schema.String,
  }),
})

// Emitted when a todo item is added to this workspace
const todoAdded = Events.synced({
  name: 'v1.TodoAdded',
  schema: Schema.Struct({ todoId: Schema.String, text: Schema.String }),
})

// Emitted when a todo item is marked as completed
const todoCompleted = Events.synced({
  name: 'v1.TodoCompleted',
  schema: Schema.Struct({ todoId: Schema.String }),
})

// Emitted when a todo item is deleted (soft delete)
const todoDeleted = Events.synced({
  name: 'v1.TodoDeleted',
  schema: Schema.Struct({
    todoId: Schema.String,
    deletedAt: Schema.DateFromString.check(Schema.isDateValid()),
  }),
})

// Emitted when a new user joins this workspace
const userJoined = Events.synced({
  name: 'v1.UserJoined',
  schema: Schema.Struct({ username: Schema.String }),
})

export const workspaceEvents = { workspaceCreated, todoAdded, todoCompleted, todoDeleted, userJoined }

// Table for the workspace itself (only one row as this store is per-workspace)
const workspaceTable = State.SQLite.table({
  name: 'workspace',
  columns: {
    workspaceId: State.SQLite.text({ primaryKey: true }),
    name: State.SQLite.text(),
    createdByUsername: State.SQLite.text(),
  },
})

// Table for the todo items in this workspace
const todosTable = State.SQLite.table({
  name: 'todos',
  columns: {
    todoId: State.SQLite.text({ primaryKey: true }),
    text: State.SQLite.text(),
    completed: State.SQLite.boolean({ default: false }),
    // Using soft delete by adding a deletedAt timestamp
    deletedAt: State.SQLite.integer({ nullable: true, schema: Schema.DateFromMillis }),
  },
})

// Table for members of this workspace
const membersTable = State.SQLite.table({
  name: 'members',
  columns: {
    username: State.SQLite.text({ primaryKey: true }),
    // Could add role/permissions here later
  },
})

export const workspaceTables = { workspace: workspaceTable, todos: todosTable, members: membersTable }

const materializers = State.SQLite.materializers(workspaceEvents, {
  'v1.WorkspaceCreated': ({ workspaceId, name, createdByUsername }) => [
    workspaceTables.workspace.insert({ workspaceId, name, createdByUsername }),
    // Add the creator as the first member
    workspaceTables.members.insert({ username: createdByUsername }),
  ],
  'v1.TodoAdded': ({ todoId, text }) => workspaceTables.todos.insert({ todoId, text }),
  'v1.TodoCompleted': ({ todoId }) => workspaceTables.todos.update({ completed: true }).where({ todoId }),
  'v1.TodoDeleted': ({ todoId, deletedAt }) => workspaceTables.todos.update({ deletedAt }).where({ todoId }),
  'v1.UserJoined': ({ username }) => workspaceTables.members.insert({ username }),
})

const state = State.SQLite.makeState({ tables: workspaceTables, materializers })

export const schema = makeSchema({ events: workspaceEvents, state })

User store:

user.store.ts user.schema.ts

import { makePersistedAdapter } from '@livestore/adapter-web'
import sharedWorker from '@livestore/adapter-web/shared-worker?sharedworker'
import { useStore } from '@livestore/react'

import { schema } from './user.schema.ts'
import worker from './user.worker.ts?worker'

const adapter = makePersistedAdapter({
  storage: { type: 'opfs' },
  worker,
  sharedWorker,
})

// Hook to access the current user's store
export const useCurrentUserStore = () =>
  useStore({
    storeId: 'user-current', // Backend should resolve this to the authenticated user's store
    schema,
    adapter,
    unusedCacheTime: Number.POSITIVE_INFINITY, // Keep user store in memory indefinitely
  })

import { Events, makeSchema, Schema, State } from '@livestore/livestore'

// Emitted when this user creates a new workspace
const workspaceCreated = Events.synced({
  name: 'v1.WorkspaceCreated',
  schema: Schema.Struct({ workspaceId: Schema.String, name: Schema.String }),
})

// Emitted when this user joins an existing workspace
const workspaceJoined = Events.synced({
  name: 'v1.WorkspaceJoined',
  schema: Schema.Struct({ workspaceId: Schema.String, name: Schema.String }),
})

export const userEvents = { workspaceCreated, workspaceJoined }

// Table to store basic user info
// Contains only one row as this store is per-user.
const userTable = State.SQLite.table({
  name: 'user',
  columns: {
    // Assuming username is unique and used as the identifier
    username: State.SQLite.text({ primaryKey: true }),
  },
})

// Table to track which workspaces this user is part of
const userWorkspacesTable = State.SQLite.table({
  name: 'userWorkspaces',
  columns: {
    workspaceId: State.SQLite.text({ primaryKey: true }),
    name: State.SQLite.text(),
    // Could add role/permissions here later
  },
})

export const userTables = { user: userTable, userWorkspaces: userWorkspacesTable }

const materializers = State.SQLite.materializers(userEvents, {
  // When the user creates or joins a workspace, add it to their workspace table
  'v1.WorkspaceCreated': ({ workspaceId, name }) => userTables.userWorkspaces.insert({ workspaceId, name }),
  'v1.WorkspaceJoined': ({ workspaceId, name }) => userTables.userWorkspaces.insert({ workspaceId, name }),
})

const state = State.SQLite.makeState({ tables: userTables, materializers })

export const schema = makeSchema({ events: userEvents, state })

Set up the store registry

Create a StoreRegistry and provide it to your React app:

App.tsx

import { type ReactNode, useState } from 'react'
import { unstable_batchedUpdates as batchUpdates } from 'react-dom'

import { StoreRegistry } from '@livestore/livestore'
import { StoreRegistryProvider } from '@livestore/react'

export const App = ({ children }: { children: ReactNode }) => {
  const [storeRegistry] = useState(
    () =>
      new StoreRegistry({
        defaultOptions: {
          batchUpdates,
        },
      }),
  )

  return <StoreRegistryProvider storeRegistry={storeRegistry}>{children}</StoreRegistryProvider>
}

Accessing stores

Use the useStore() hook to access specific workspace instances:

Workspace.tsx user.schema.ts user.store.ts workspace.schema.ts workspace.store.ts

import { useCallback } from 'react'

import { queryDb } from '@livestore/livestore'
import { useStore } from '@livestore/react'

import { userTables } from './user.schema.ts'
import { useCurrentUserStore } from './user.store.ts'
import { workspaceEvents, workspaceTables } from './workspace.schema.ts'
import { workspaceStoreOptions } from './workspace.store.ts'

// Component that accesses a specific workspace store
export const Workspace = ({ workspaceId }: { workspaceId: string }) => {
  const userStore = useCurrentUserStore()
  const workspaceStore = useStore(workspaceStoreOptions(workspaceId))

  // Check if this workspace exists in user's workspace list
  const [knownWorkspace] = userStore.useQuery(queryDb(userTables.userWorkspaces.select().where({ workspaceId })))

  // Query workspace data
  const [workspace] = workspaceStore.useQuery(queryDb(workspaceTables.workspace.select().limit(1)))
  const todos = workspaceStore.useQuery(queryDb(workspaceTables.todos.select()))

  // Workspace not in user's list → truly doesn't exist
  if (knownWorkspace == null) return <div>Workspace not found</div>

  // Workspace is in user's list but not yet initialized → loading state
  if (workspace == null) return <div>Loading workspace...</div>

  const addTodo = useCallback(
    (text: string) => {
      workspaceStore.commit(
        workspaceEvents.todoAdded({
          todoId: `todo-${Date.now()}`,
          text,
        }),
      )
    },
    [workspaceStore],
  )

  const addNewTodo = useCallback(() => addTodo('New todo'), [addTodo])

  return (
    <div>
      <h2>{workspace.name}</h2>
      <p>Created by: {workspace.createdByUsername}</p>
      <p>Store ID: {workspaceStore.storeId}</p>

      <h3>Todos ({todos.length})</h3>
      <ul>
        {todos.map((todo) => (
          <li key={todo.todoId}>
            {todo.text} {todo.completed === true ? '✓' : ''}
          </li>
        ))}
      </ul>

      <button type="button" onClick={addNewTodo}>
        Add Todo
      </button>
    </div>
  )
}

import { Events, makeSchema, Schema, State } from '@livestore/livestore'

// Emitted when this user creates a new workspace
const workspaceCreated = Events.synced({
  name: 'v1.WorkspaceCreated',
  schema: Schema.Struct({ workspaceId: Schema.String, name: Schema.String }),
})

// Emitted when this user joins an existing workspace
const workspaceJoined = Events.synced({
  name: 'v1.WorkspaceJoined',
  schema: Schema.Struct({ workspaceId: Schema.String, name: Schema.String }),
})

export const userEvents = { workspaceCreated, workspaceJoined }

// Table to store basic user info
// Contains only one row as this store is per-user.
const userTable = State.SQLite.table({
  name: 'user',
  columns: {
    // Assuming username is unique and used as the identifier
    username: State.SQLite.text({ primaryKey: true }),
  },
})

// Table to track which workspaces this user is part of
const userWorkspacesTable = State.SQLite.table({
  name: 'userWorkspaces',
  columns: {
    workspaceId: State.SQLite.text({ primaryKey: true }),
    name: State.SQLite.text(),
    // Could add role/permissions here later
  },
})

export const userTables = { user: userTable, userWorkspaces: userWorkspacesTable }

const materializers = State.SQLite.materializers(userEvents, {
  // When the user creates or joins a workspace, add it to their workspace table
  'v1.WorkspaceCreated': ({ workspaceId, name }) => userTables.userWorkspaces.insert({ workspaceId, name }),
  'v1.WorkspaceJoined': ({ workspaceId, name }) => userTables.userWorkspaces.insert({ workspaceId, name }),
})

const state = State.SQLite.makeState({ tables: userTables, materializers })

export const schema = makeSchema({ events: userEvents, state })

import { makePersistedAdapter } from '@livestore/adapter-web'
import sharedWorker from '@livestore/adapter-web/shared-worker?sharedworker'
import { useStore } from '@livestore/react'

import { schema } from './user.schema.ts'
import worker from './user.worker.ts?worker'

const adapter = makePersistedAdapter({
  storage: { type: 'opfs' },
  worker,
  sharedWorker,
})

// Hook to access the current user's store
export const useCurrentUserStore = () =>
  useStore({
    storeId: 'user-current', // Backend should resolve this to the authenticated user's store
    schema,
    adapter,
    unusedCacheTime: Number.POSITIVE_INFINITY, // Keep user store in memory indefinitely
  })

import { Events, makeSchema, Schema, State } from '@livestore/livestore'

// Emitted when a new workspace is created (originates this store)
const workspaceCreated = Events.synced({
  name: 'v1.WorkspaceCreated',
  schema: Schema.Struct({
    workspaceId: Schema.String,
    name: Schema.String,
    createdByUsername: Schema.String,
  }),
})

// Emitted when a todo item is added to this workspace
const todoAdded = Events.synced({
  name: 'v1.TodoAdded',
  schema: Schema.Struct({ todoId: Schema.String, text: Schema.String }),
})

// Emitted when a todo item is marked as completed
const todoCompleted = Events.synced({
  name: 'v1.TodoCompleted',
  schema: Schema.Struct({ todoId: Schema.String }),
})

// Emitted when a todo item is deleted (soft delete)
const todoDeleted = Events.synced({
  name: 'v1.TodoDeleted',
  schema: Schema.Struct({
    todoId: Schema.String,
    deletedAt: Schema.DateFromString.check(Schema.isDateValid()),
  }),
})

// Emitted when a new user joins this workspace
const userJoined = Events.synced({
  name: 'v1.UserJoined',
  schema: Schema.Struct({ username: Schema.String }),
})

export const workspaceEvents = { workspaceCreated, todoAdded, todoCompleted, todoDeleted, userJoined }

// Table for the workspace itself (only one row as this store is per-workspace)
const workspaceTable = State.SQLite.table({
  name: 'workspace',
  columns: {
    workspaceId: State.SQLite.text({ primaryKey: true }),
    name: State.SQLite.text(),
    createdByUsername: State.SQLite.text(),
  },
})

// Table for the todo items in this workspace
const todosTable = State.SQLite.table({
  name: 'todos',
  columns: {
    todoId: State.SQLite.text({ primaryKey: true }),
    text: State.SQLite.text(),
    completed: State.SQLite.boolean({ default: false }),
    // Using soft delete by adding a deletedAt timestamp
    deletedAt: State.SQLite.integer({ nullable: true, schema: Schema.DateFromMillis }),
  },
})

// Table for members of this workspace
const membersTable = State.SQLite.table({
  name: 'members',
  columns: {
    username: State.SQLite.text({ primaryKey: true }),
    // Could add role/permissions here later
  },
})

export const workspaceTables = { workspace: workspaceTable, todos: todosTable, members: membersTable }

const materializers = State.SQLite.materializers(workspaceEvents, {
  'v1.WorkspaceCreated': ({ workspaceId, name, createdByUsername }) => [
    workspaceTables.workspace.insert({ workspaceId, name, createdByUsername }),
    // Add the creator as the first member
    workspaceTables.members.insert({ username: createdByUsername }),
  ],
  'v1.TodoAdded': ({ todoId, text }) => workspaceTables.todos.insert({ todoId, text }),
  'v1.TodoCompleted': ({ todoId }) => workspaceTables.