Getting started with LiveStore + React

Prerequisites

• Recommended: Bun 1.2 or higher
• Node.js 23.0.0 or higher

Option A: Quick start

For a quick start, we recommend using our template app following the steps below.

For existing projects, see Existing project setup.

1. Set up project from template

   bun

   bunx tiged "github:livestorejs/livestore/examples/web-todomvc-sync-cf#dev" livestore-app

   pnpm

   pnpm dlx tiged "github:livestorejs/livestore/examples/web-todomvc-sync-cf#dev" livestore-app

   npm

   npx tiged "github:livestorejs/livestore/examples/web-todomvc-sync-cf#dev" livestore-app

   Replace livestore-app with your desired app name.

2. Install dependencies

   It’s strongly recommended to use bun or pnpm for the simplest and most reliable dependency setup (see note on package management for more details).

   bun

   bun install

   pnpm

   pnpm install

   npm

   npm install

   Pro tip: You can use direnv to manage environment variables.

3. Run dev environment

   bun

   bun dev

   pnpm

   pnpm dev

   npm

   npm run dev

4. Open browser

   Open http://localhost:60000 in your browser.

   You can also open the devtools by going to http://localhost:60000/_livestore.

Option B: Existing project setup

1. Install dependencies

   bun

   bun install @livestore/livestore@0.4.0-dev.7 @livestore/wa-sqlite@0.4.0-dev.7 @livestore/adapter-web@0.4.0-dev.7 @livestore/react@0.4.0-dev.7 @livestore/peer-deps@0.4.0-dev.7 @livestore/sync-cf/client@0.4.0-dev.7 @livestore/devtools-vite@0.4.0-dev.7

   pnpm

   pnpm add @livestore/livestore@0.4.0-dev.7 @livestore/wa-sqlite@0.4.0-dev.7 @livestore/adapter-web@0.4.0-dev.7 @livestore/react@0.4.0-dev.7 @livestore/peer-deps@0.4.0-dev.7 @livestore/sync-cf/client@0.4.0-dev.7 @livestore/devtools-vite@0.4.0-dev.7

   npm

   npm install @livestore/livestore@0.4.0-dev.7 @livestore/wa-sqlite@0.4.0-dev.7 @livestore/adapter-web@0.4.0-dev.7 @livestore/react@0.4.0-dev.7 @livestore/peer-deps@0.4.0-dev.7 @livestore/sync-cf/client@0.4.0-dev.7 @livestore/devtools-vite@0.4.0-dev.7

2. Update Vite config

   Add the following code to your vite.config.js file:

   vite.config.js

   import { spawn } from 'node:child_process'
   import { livestoreDevtoolsPlugin } from '@livestore/devtools-vite'
   import react from '@vitejs/plugin-react'
   import { defineConfig } from 'vite'
   
   export default defineConfig({
     server: {
       port: process.env.PORT ? Number(process.env.PORT) : 60_001,
       fs: { strict: false },
     },
     worker: { format: 'es' },
     plugins: [
       react(),
       livestoreDevtoolsPlugin({ schemaPath: './src/livestore/schema.ts' }),
       // Running `wrangler dev` as part of `vite dev` needed for `@livestore/sync-cf`
       {
         name: 'wrangler-dev',
         configureServer: async (server) => {
           const wrangler = spawn('./node_modules/.bin/wrangler', ['dev', '--port', '8787'], {
             stdio: ['ignore', 'inherit', 'inherit'],
           })
   
           const shutdown = () => {
             if (wrangler.killed === false) {
               wrangler.kill()
             }
             process.exit(0)
           }
   
           server.httpServer?.on('close', shutdown)
           process.on('SIGTERM', shutdown)
           process.on('SIGINT', shutdown)
   
           wrangler.on('exit', (code) => console.error(`wrangler dev exited with code ${code}`))
         },
       },
     ],
   })

Define Your Schema

Create a file named schema.ts inside the src/livestore folder. This file defines your LiveStore schema consisting of your app’s event definitions (describing how data changes), derived state (i.e. SQLite tables), and materializers (how state is derived from events).

Here’s an example schema:

src/livestore/schema.ts

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

// You can model your state as SQLite tables (https://docs.livestore.dev/reference/state/sqlite-schema)
export const tables = {
  todos: State.SQLite.table({
    name: 'todos',
    columns: {
      id: State.SQLite.text({ primaryKey: true }),
      text: State.SQLite.text({ default: '' }),
      completed: State.SQLite.boolean({ default: false }),
      deletedAt: State.SQLite.integer({ nullable: true, schema: Schema.DateFromNumber }),
    },
  }),
  // Client documents can be used for local-only state (e.g. form inputs)
  uiState: State.SQLite.clientDocument({
    name: 'uiState',
    schema: Schema.Struct({ newTodoText: Schema.String, filter: Schema.Literal('all', 'active', 'completed') }),
    default: { id: SessionIdSymbol, value: { newTodoText: '', filter: 'all' } },
  }),
}

// Events describe data changes (https://docs.livestore.dev/reference/events)
export const events = {
  todoCreated: Events.synced({
    name: 'v1.TodoCreated',
    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
  }),
  todoCompleted: Events.synced({
    name: 'v1.TodoCompleted',
    schema: Schema.Struct({ id: Schema.String }),
  }),
  todoUncompleted: Events.synced({
    name: 'v1.TodoUncompleted',
    schema: Schema.Struct({ id: Schema.String }),
  }),
  todoDeleted: Events.synced({
    name: 'v1.TodoDeleted',
    schema: Schema.Struct({ id: Schema.String, deletedAt: Schema.Date }),
  }),
  todoClearedCompleted: Events.synced({
    name: 'v1.TodoClearedCompleted',
    schema: Schema.Struct({ deletedAt: Schema.Date }),
  }),
  uiStateSet: tables.uiState.set,
}

// Materializers are used to map events to state (https://docs.livestore.dev/reference/state/materializers)
const materializers = State.SQLite.materializers(events, {
  'v1.TodoCreated': ({ id, text }) => tables.todos.insert({ id, text, completed: false }),
  'v1.TodoCompleted': ({ id }) => tables.todos.update({ completed: true }).where({ id }),
  'v1.TodoUncompleted': ({ id }) => tables.todos.update({ completed: false }).where({ id }),
  'v1.TodoDeleted': ({ id, deletedAt }) => tables.todos.update({ deletedAt }).where({ id }),
  'v1.TodoClearedCompleted': ({ deletedAt }) => tables.todos.update({ deletedAt }).where({ completed: true }),
})

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

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

Create the LiveStore Worker

Create a file named livestore.worker.ts inside the src folder. This file will contain the LiveStore web worker. When importing this file, make sure to add the ?worker extension to the import path to ensure that Vite treats it as a worker file.

src/livestore.worker.ts

import { makeWorker } from '@livestore/adapter-web/worker'

import { schema } from './livestore/schema.ts'

makeWorker({ schema })

Add the LiveStore Provider

To make the LiveStore available throughout your app, wrap your app’s root component with the LiveStoreProvider component from @livestore/react. This provider manages your app’s data store, loading, and error states.

Here’s an example:

src/Root.tsx

/// <reference types="vite/client" />

import { makePersistedAdapter } from '@livestore/adapter-web'
import LiveStoreSharedWorker from '@livestore/adapter-web/shared-worker?sharedworker'
import { LiveStoreProvider } from '@livestore/react'
import type React from 'react'
import { unstable_batchedUpdates as batchUpdates } from 'react-dom'
import { schema } from './livestore/schema.ts'
import LiveStoreWorker from './livestore.worker.ts?worker'

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

export const App: React.FC = () => (
  <LiveStoreProvider
    schema={schema}
    adapter={adapter}
    renderLoading={(_) => <div>Loading LiveStore ({_.stage})...</div>}
    batchUpdates={batchUpdates}
    storeId="my-app-store"
  >
    <div className="todoapp">{/* Your app components go here */}</div>
  </LiveStoreProvider>
)

Commit events

After wrapping your app with the LiveStoreProvider, you can use the useStore hook from any component to commit events.

Here’s an example:

src/components/Header.tsx

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

import { events, tables } from './livestore/schema.ts'

const uiState$ = queryDb(tables.uiState.get(), { label: 'uiState' })

export const Header: React.FC = () => {
  const { store } = useStore()
  const { newTodoText } = store.useQuery(uiState$)

  const updateNewTodoText = (text: string) => store.commit(events.uiStateSet({ newTodoText: text }))

  const createTodo = () =>
    store.commit(
      events.todoCreated({ id: crypto.randomUUID(), text: newTodoText }),
      events.uiStateSet({ newTodoText: '' }),
    )

  return (
    <header className="header">
      <h1>TodoMVC</h1>
      <input
        className="new-todo"
        placeholder="What needs to be done?"
        value={newTodoText}
        onChange={(e) => updateNewTodoText(e.target.value)}
        onKeyDown={(e) => {
          if (e.key === 'Enter') {
            createTodo()
          }
        }}
      />
    </header>
  )
}

Queries

To retrieve data from the database, first define a query using queryDb from @livestore/livestore. Then, execute the query with the useQuery hook from @livestore/react.

Consider abstracting queries into a separate file to keep your code organized, though you can also define them directly within components if preferred.

Here’s an example:

src/components/MainSection.tsx

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

import { events, tables } from './livestore/schema.ts'

const uiState$ = queryDb(tables.uiState.get(), { label: 'uiState' })

const visibleTodos$ = queryDb(
  (get) => {
    const { filter } = get(uiState$)
    return tables.todos.where({
      deletedAt: null,
      completed: filter === 'all' ? undefined : filter === 'completed',
    })
  },
  { label: 'visibleTodos' },
)

export const MainSection: React.FC = () => {
  const { store } = useStore()

  const toggleTodo = React.useCallback(
    ({ id, completed }: typeof tables.todos.Type) =>
      store.commit(completed ? events.todoUncompleted({ id }) : events.todoCompleted({ id })),
    [store],
  )

  const visibleTodos = store.useQuery(visibleTodos$)

  return (
    <section className="main">
      <ul className="todo-list">
        {visibleTodos.map((todo) => (
          <li key={todo.id}>
            <div className="view">
              <input
                type="checkbox"
                className="toggle"
                id={`todo-${todo.id}`}
                checked={todo.completed}
                onChange={() => toggleTodo(todo)}
              />
              <label htmlFor={`todo-${todo.id}`}>{todo.text}</label>
              <button
                type="button"
                className="destroy"
                onClick={() => store.commit(events.todoDeleted({ id: todo.id, deletedAt: new Date() }))}
              />
            </div>
          </li>
        ))}
      </ul>
    </section>
  )
}