# 3. Read and write todos via LiveStore
import { Tabs, TabItem, Code } from '@astrojs/starlight/components';
import LivestoreDataFlowDiagram from '../../_assets/diagrams/tutorial-chapter-3-2-livestore-data-flow.tldr?tldraw';
Now on to the fun part! In this section, you'll set up LiveStore so that the todos that you're creating will persist and survive page refreshes and dev server reloads.
:::note[Help improve LiveStore]
Remember that LiveStore is still early and its developer surface and API not yet fully optimized. Bear with us through the setup and boilerplate code that's needed for a running application—it'll be worth it!
Also: If you have ideas for improving the developer experience for LiveStore, please [raise an issue](https://github.com/livestorejs/livestore/issues). This project is fully open-source and depends on people like you.
:::
## Install LiveStore dependencies
Start by installing the necessary dependencies:
Expand to view details about the packages
Here's an overview of each of these dependencies:
- `@livestore/livestore@0.4.0-dev.14` → Implements the core LiveStore functionality (schema, events, queries, ...).
- `@livestore/wa-sqlite@0.4.0-dev.14` → Implements usage of a [SQLite build in WebAssembly](https://github.com/livestorejs/wa-sqlite), so you can use SQLite inside your browser.
- `@livestore/adapter-web@0.4.0-dev.14` → Implements the [LiveStore web adapter.](/platform-adapters/web-adapter)
- `@livestore/react@0.4.0-dev.14` → Provides [LiveStore integration for React](https://github.com/livestorejs/wa-sqlite).
- `@livestore/peer-deps@0.4.0-dev.14` → Required to [satisfy LiveStore peer dependencies](https://dev.docs.livestore.dev/misc/package-management/#peer-dependencies).
## Define your LiveStore schema
In this step, you're going to define the [schema](/building-with-livestore/state/sqlite-schema) that LiveStore uses to represent the data of your app. The schema is one of the core concepts of LiveStore.
Your LiveStore-related files typically live in a `livestore` directory in your app, so create that first:
```bash
mkdir src/livestore
touch src/livestore/schema.ts
```
The schema contains three major components:
- The [**table**](/building-with-livestore/state/sqlite-schema#defining-tables) structures of your local SQLite database.
- The [**events**](https://dev.docs.livestore.dev/reference/events/) that can be emitted by your app.
- The [**materializers**](/building-with-livestore/state/materializers) that use the events to alter the state of your database.
Here's how you define the schema for the current version of the todo app:
```ts title="src/livestore/schema.ts"
import { Events, makeSchema, Schema, State } from '@livestore/livestore'
export const tables = {
todos: State.SQLite.table({
name: 'todos',
columns: {
id: State.SQLite.integer({ primaryKey: true }),
text: State.SQLite.text({ default: '' }),
},
})
}
export const events = {
todoCreated: Events.synced({
name: 'v1.TodoCreated',
schema: Schema.Struct({ id: Schema.Number, text: Schema.String }),
}),
todoDeleted: Events.synced({
name: 'v1.TodoDeleted',
schema: Schema.Struct({ id: Schema.Number }),
}),
}
const materializers = State.SQLite.materializers(events, {
'v1.TodoCreated': ({ id, text }) => tables.todos.insert({ id, text }),
'v1.TodoDeleted': ({ id }) => tables.todos.delete().where({ id: id }),
})
const state = State.SQLite.makeState({ tables, materializers })
export const schema = makeSchema({ events, state })
```
Here's a quick summary of the code:
- `tables` contains the definitions of your SQLite table structures. It currently defines a single `todos` table with two columns called `id` and `text`.
- `events` defines the types of events that your app can emit. It currently defines the `todoCreated` and `todoDeleted` events with an attached `schema` property which defines the shape of the event.
- `materializers` are the functions that are invoked for each event. In them, you define what should happen when the event gets fired. Right now, the `v1.TodoCreated` event results in an `insert` operation in the database while `v1.TodoDeleted` will remove a row from the database via a `delete` operation.
The `tables`, `events` and `materializers` are packaged up into a `schema` object that's needed in the parts of your app where you interact with LiveStore.
:::note[Versioning events and materializers]
You may have noticed that event and materializer names are prefixed with `v1`.
It's good practice in LiveStore to version your events and materializers to ensure future compatibility between them as your app evolves.
:::
## Configure your React/Vite app to use LiveStore
To now "connect" LiveStore with your React app, you need to:
1. Create the [LiveStore web worker](/platform-adapters/web-adapter#web-worker) that is responsible for the logic of persisting data on your file system.
2. Create a LiveStore [adapter](/platform-adapters/web-adapter) that enables persistence with local SQLite via [OPFS](https://web.dev/articles/origin-private-file-system).
3. Create a store configuration file that exports a custom hook wrapping [`useStore()`](/framework-integrations/react-integration#1-configure-the-store).
4. Create and provide a `StoreRegistry` with [``](/framework-integrations/react-integration#2-set-up-the-registry) in `main.tsx`.
5. Update your Vite Config to work with LiveStore.
Let's get started!
First, create a new file for the LiveStore web worker:
```bash
touch src/livestore/livestore.worker.ts
```
Then, add the following code to it:
```ts file="src/livestore/livestore.worker.ts"
import { makeWorker } from '@livestore/adapter-web/worker'
import { schema } from './schema.ts'
makeWorker({ schema })
```
This is boilerplate code that you'll almost never need to touch. (In this tutorial, it'll only be edited once when we introduce syncing data to Cloudflare.)
:::note[Special syntax for importing web worker files in Vite]
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](https://vite.dev/guide/features.html#web-workers).
:::
Next, create a `store.ts` file that defines your store configuration and a `useAppStore()` hook:
```bash
touch src/livestore/store.ts
```
```ts title="src/livestore/store.ts"
import { makePersistedAdapter } from '@livestore/adapter-web'
import { useStore } from '@livestore/react'
import LiveStoreSharedWorker from '@livestore/adapter-web/shared-worker?sharedworker'
import { unstable_batchedUpdates as batchUpdates } from 'react-dom'
import { schema } from './schema.ts'
import LiveStoreWorker from './livestore.worker.ts?worker'
const adapter = makePersistedAdapter({
storage: { type: 'opfs' },
worker: LiveStoreWorker,
sharedWorker: LiveStoreSharedWorker,
})
export const useAppStore = () =>
useStore({
storeId: 'todo-db-tutorial',
schema,
adapter,
batchUpdates,
})
```
Then, update `main.tsx` to wrap your `` component inside the ``:
```tsx title="src/main.tsx"
import { createRoot } from 'react-dom/client'
import './index.css'
import App from './App.tsx'
import { StoreRegistry } from '@livestore/livestore'
import { StoreRegistryProvider } from '@livestore/react'
import { Suspense, useState } from 'react'
const Root = () => {
const [storeRegistry] = useState(() => new StoreRegistry())
return (
Loading LiveStore...}>
)
}
createRoot(document.getElementById('root')!).render()
```
:::note[So many "workers" ...]
There's some ambiguity with the "worker" terminology in this tutorial. In general, there are three different kinds of Workers at play.
- The **LiveStore web worker** (`LiveStoreWorker`); this is the Worker you defined in `livestore.worker.ts`. Technically, this is a _browser_ web worker, i.e. a separate JavaScript thread that runs in the browser, isolated from the main UI thread.
- The **LiveStore shared web worker** (`LiveStoreSharedWorker`); you just imported it from `@livestore/adapter-web/shared-worker`, also a _browser_ web worker. It's actually more of an _implementation detail_ but currently required to be exposed, so that the setup works with Vite.
- The **Cloudflare Worker** that will automatically sync the data in the background; you'll set this up in the next step.
Note that both the LiveStore web worker and the LiveStore Shared web worker are regular [web workers,](https://www.dhiwise.com/post/web-workers-vs-service-workers-in-javascript#what-are-web-workers-) not [service workers](https://www.dhiwise.com/post/web-workers-vs-service-workers-in-javascript#what-are-service-workers-)!
Here's how to think about the workers in the context of browser tabs (or windows):
```
Tab 1 ──┐
Tab 2 ──┼──→ Shared Worker (tab coordination) ──→ Web Worker (persistence)
Tab 3 ──┘
```
:::
Finally, update your Vite Config to enable usage of WebAssembly:
```diff title="vite.config.ts" lang="ts"
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import { cloudflare } from '@cloudflare/vite-plugin'
export default defineConfig({
plugins: [
react(),
tailwindcss(),
cloudflare(),
],
+ optimizeDeps: {
+ exclude: ['@livestore/wa-sqlite'],
+ },
})
```
Now, your app is set up to start reading and writing data in a local SQLite database via LiveStore. If you run the app via `pnpm dev`, you'll briefly see a loading screen (the Suspense fallback) before the todo list UI from the previous steps will appear again:
The todos themselves are not yet persisted because you haven't modified the logic for managing state in `App.tsx`. That's what you'll do next.
## Read and write todos from local SQLite via LiveStore
The current version of the app still stores the todos _in-memory_ via the [state](https://react.dev/learn/state-a-components-memory) of your `` component. However, with the basic LiveStore setup in place, you can now move to persisting your todos inside SQLite via LiveStore!
In order to read todos, you need to define a LiveStore [query](/building-with-livestore/state/sql-queries). LiveStore queries are _live_ or _reactive_, meaning they will automatically update your UI components when the underlying data changes.
Here's how you can define and use a query to fetch all todos from the local SQLite database using LiveStore inside the `` component (you don't need to update your code yet, you'll get the full snippet at the end of this section):
```diff title="src/App.tsx" lang="ts"
function App() {
+ const store = useAppStore()
// The trailing `$` is a convention to indicate that this
// variable is a "live query".
+ const todos$ = queryDb(() => tables.todos.select())
// `todos` is an array containing all the todos from the DB.
// When rendering the component, you can do {todos.map(todo => ...
// and access `todo.text` and `todo.id` as before.
+ const todos = store.useQuery(todos$)
- const [todos, setTodos] = useState([])
// ... remaining code for the `` component
}
```
With this change, you're now reading the `todos` from LiveStore (where they're persisted) instead of using React's ephemeral state.
This was only half of the job though: Right now your code would throw a type error because it still uses `setTodos` to update the local state. You need to update this to use the `todoCreated` and `todoDeleted` events you defined in `src/livestore/schema.ts`:
```diff title="src/App.tsx" lang="ts"
function App() {
const store = useAppStore()
const todos$ = queryDb(() => tables.todos.select())
const todos = store.useQuery(todos$)
// Commit an event to the `store` instead of
// updating local React state.
const addTodo = () => {
+ store.commit(
+ events.todoCreated({ id: Date.now(), text: input }),
+ )
setInput('')
}
// Commit an event to the `store` instead of
// updating local React state.
const deleteTodo = (id: number) => {
+ store.commit(
+ events.todoDeleted({ id }),
+ )
}
// ... remaining code for the `` component
}
```
See how the data now will flow through the app _unidirectionally_ with this setup?
Let's follow it from the first time the app is started:
1. The `` component registers the `todos$` "live query" with the store.
1. The query fires initially; the returned `todos` array is empty.
1. The `` component renders an empty list.
1. A user adds a `todo`; the `todoCreated` event is triggered and committed to the DB.
1. The `v1.TodoCreated` materializer is invoked and writes the data into the DB.
1. The `todos$` query fires again because the state of the DB changed; the returned `todos` array now contains the newly created todo.
1. The `` component renders a single todo.
Now try it out! Here's the full code for `App.tsx` that you can copy and paste:
```ts title="src/App.tsx"
import { useState } from 'react'
import { tables, events } from './livestore/schema'
import { useAppStore } from './livestore/store'
import { queryDb } from '@livestore/livestore'
function App() {
const store = useAppStore()
const todos$ = queryDb(() => tables.todos.select())
const todos = store.useQuery(todos$)
const [input, setInput] = useState('')
const addTodo = () => {
if (input.trim()) {
store.commit(
events.todoCreated({ id: Date.now(), text: input }),
)
setInput('')
}
}
const deleteTodo = (id: number) => {
store.commit(
events.todoDeleted({ id }),
)
}
const handleKeyDown = (e: React.KeyboardEvent) => {
if (e.key === 'Enter') {
addTodo()
}
}
return (
)
}
export default App
```
Try adding a few todos and then refresh the browser (or restart your development server):
In addition to the persistence, you can now observe the following behaviour:
- You can open multiple browser tabs/windows, make edits to the todo list and see live updates when you make changes in one of them.
- You can stop and restart the local version of your app and the todos will be persisted.
- If you open the app in an incognito tab or a different browser, the list of todos will be empty again; that's because the _Shared web worker_ only works in the same browser "session"; incognito tabs and different browsers use a different session.
Expand to learn about browser isolation/sessions
**Regular browser tab/windows**
- All regular (i.e. "not incognito") tabs/windows share the same browser session.
- The LiveStore shared web worker is shared across all these tabs/windows.
- OPFS storage is shared across the origin.
- ✅ Real-time sync works because they're all using the same LiveStore shared web worker and storage.
**Incognito windows**
- Incognito mode creates a separate session from regular browsing.
- However, multiple incognito tabs/windows opened in the same incognito session still share:
- The same LiveStore shared web worker instance.
- The same OPFS storage (within that incognito session).
- Each incognito session gets isolated storage, but windows within that session are _not_ isolated from each other.
Think of it this way:
- Regular tabs/windows = Session A (all tabs/windows share the same data).
- Incognito tabs/windows = Session B (all incognito tabs/windows share the same data).
**To get true isolation**
If you want completely isolated instances, you'd need to use:
- **Different browser profiles** - Chrome profiles are truly isolated.
- **Different browsers** - Chrome vs Firefox vs Safari.
- **Different devices** (only possible with the deployed app) - Your computer vs your phone.
Now, you can also deploy the app:
Here's a little GIF demonstrating the current state of the live updates via browser isolation. On the left, we have two regular Chrome windows, on the right, two Safari windows.
- When a change is made in one Chrome window, it is automatically reflected in the other Chrome window.
- Similarly, when a change is made in one Safari window, it is automatically reflected in the other Safari window.
To recap, here's a visualization of the data flow in the app at this point:
## Set up LiveStore DevTools
You may have wondered: "If the data is persisted, _where_ is it?". If the data is somewhere on your file system, you _should_ be able to spin up a database viewer of your choice and inspect the local SQLite DB file.
Unfortunately, that's not how OPFS works. While the SQLite files do exist _somewhere_ on your file system, they are hidden in the browser's internals and not easily accessible.
That being said, there is a convenient way how you can actually see the data on your file system: Using [LiveStore DevTools](/building-with-livestore/devtools)!
:::note[LiveStore DevTools are a sponsor-only feature]
Our goal is to grow the project in a [sustainable](/sustainable-open-source/sponsoring#goal-sustainable-open-source) way (e.g. not rely on VC funding), that's why DevTools are currently a [sponsor-only](/sustainable-open-source/sponsoring) feature.
That being said, we still include them in this tutorial since you'll be able to use them without sponsorship for one week.
LiveStore can only exist thanks to its generous sponsors, please consider becoming one of them if the project is of value to you. ❤️
:::
To start using DevTools, first install the package for the web adapter you're using:
Next, update your Vite Config to add the `livestoreDevtoolsPlugin`. It should look as follows:
```diff title="vite.config.ts" lang="ts"
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import { cloudflare } from '@cloudflare/vite-plugin'
+import { livestoreDevtoolsPlugin } from '@livestore/devtools-vite'
// https://vite.dev/config/
export default defineConfig({
plugins: [
react(),
tailwindcss(),
cloudflare(),
+ livestoreDevtoolsPlugin({ schemaPath: './src/livestore/schema.ts' })
],
optimizeDeps: {
exclude: ['@livestore/wa-sqlite'],
},
})
```
Now, in the developer console of your browser, you can find the **LiveStore** tab with details about the current LiveStore internals:
There are several tabs in the LiveStore DevTools:
- **Database**: Browse the data that's currently in your DB, send SQL queries, export the database to your file system, and more.
- **Queries**: Shows the last results of the currently active live queries.
- **Events**: The [event log](/understanding-livestore/event-sourcing) that stores all the events emitted by your app.
If you're curious, add and delete a few todos via the UI and observe what's happening in the three tabs.