Expo

Prerequisites

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

To use LiveStore with Expo, ensure your project has the New Architecture enabled. This is required for transactional state updates.

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 @livestore/cli@dev create --example expo-todomvc-sync-cf livestore-app

   pnpm

   pnpm dlx @livestore/cli@dev create --example expo-todomvc-sync-cf livestore-app

   npm

   npx @livestore/cli@dev create --example expo-todomvc-sync-cf livestore-app

   yarn

   yarn dlx @livestore/cli@dev create --example expo-todomvc-sync-cf 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 --node-linker=hoisted

   Make sure to use --node-linker=hoisted when installing dependencies in your project or add it to your .npmrc file.

   .npmrc

   nodeLinker=hoisted

   Hopefully Expo will also support non-hoisted setups in the future.

   npm

   npm install

   yarn

   When using yarn, make sure you’re using Yarn 4 or higher with the node-modules linker.

   yarn set version stable
   yarn config set nodeLinker node-modules
   yarn install

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

3. Run the app

   bun

   bun start

   pnpm

   pnpm start

   npm

   npm run start

   yarn

   yarn start

   In a new terminal, start the Cloudflare Worker (for the sync backend):

   bun

   bun wrangler:dev

   pnpm

   pnpm wrangler:dev

   npm

   npm run wrangler:dev

   yarn

   yarn wrangler:dev

Option B: Existing project setup

1. Install dependencies

   bun

   bun install @livestore/devtools-expo@0.5.0-dev.0 @livestore/adapter-expo@0.5.0-dev.0 @livestore/livestore@0.5.0-dev.0 @livestore/react@0.5.0-dev.0 @livestore/sync-cf/client@0.5.0-dev.0 @livestore/peer-deps@0.5.0-dev.0 expo-sqlite

   pnpm

   pnpm install @livestore/devtools-expo@0.5.0-dev.0 @livestore/adapter-expo@0.5.0-dev.0 @livestore/livestore@0.5.0-dev.0 @livestore/react@0.5.0-dev.0 @livestore/sync-cf/client@0.5.0-dev.0 @livestore/peer-deps@0.5.0-dev.0 expo-sqlite

   npm

   npm install @livestore/devtools-expo@0.5.0-dev.0 @livestore/adapter-expo@0.5.0-dev.0 @livestore/livestore@0.5.0-dev.0 @livestore/react@0.5.0-dev.0 @livestore/sync-cf/client@0.5.0-dev.0 @livestore/peer-deps@0.5.0-dev.0 expo-sqlite

   yarn

   yarn add @livestore/devtools-expo@0.5.0-dev.0 @livestore/adapter-expo@0.5.0-dev.0 @livestore/livestore@0.5.0-dev.0 @livestore/react@0.5.0-dev.0 @livestore/sync-cf/client@0.5.0-dev.0 @livestore/peer-deps@0.5.0-dev.0 expo-sqlite

2. Add Vite meta plugin to babel config file

   LiveStore Devtools uses Vite. This plugin emulates Vite’s import.meta.env functionality.

   bun

   bun add -d babel-plugin-transform-vite-meta-env

   pnpm

   pnpm add -D babel-plugin-transform-vite-meta-env

   yarn

   yarn add -D babel-plugin-transform-vite-meta-env

   npm

   npm install --save-dev babel-plugin-transform-vite-meta-env

   In your babel.config.js file, add the plugin as follows:

   babel.config.js

   module.exports = (api) => {
     api.cache(true)
     return {
       presets: [['babel-preset-expo', { unstable_transformImportMeta: true }]],
       plugins: ['babel-plugin-transform-vite-meta-env', '@babel/plugin-syntax-import-attributes'],
     }
   }

3. Update Metro config

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

   metro.config.js

   // Learn more https://docs.expo.io/guides/customizing-metro
   const { getDefaultConfig } = require('expo/metro-config')
   const { addLiveStoreDevtoolsMiddleware } = require('@livestore/devtools-expo')
   const path = require('node:path')
   
   /** @type {import('expo/metro-config').MetroConfig} */
   const config = getDefaultConfig(__dirname)
   
   // Needed for monorepo setup (can be removed in standalone projects)
   if (process.env.MONOREPO_ROOT) {
     config.watchFolders = [path.resolve(process.env.MONOREPO_ROOT)]
   }
   
   addLiveStoreDevtoolsMiddleware(config, {
     schemaPath: './src/livestore/schema.ts',
     viteConfig: (viteConfig) => {
       viteConfig.server.fs ??= {}
       viteConfig.server.fs.strict = false
       viteConfig.optimizeDeps ??= {}
       viteConfig.optimizeDeps.force = true
       return viteConfig
     },
   })
   
   module.exports = config

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:

schema.ts

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

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.DateFromMillis }),
    },
  }),
  uiState: State.SQLite.clientDocument({
    name: 'uiState',
    schema: Schema.Struct({ newTodoText: Schema.String, filter: Schema.Literals(['all', 'active', 'completed']) }),
    default: { id: SessionIdSymbol, value: { newTodoText: '', filter: 'all' } },
  }),
}

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.DateFromString,
    }),
  }),
  todoClearedCompleted: Events.synced({
    name: 'v1.TodoClearedCompleted',
    schema: Schema.Struct({ deletedAt: Schema.DateFromString }),
  }),
  uiStateSet: tables.uiState.set,
}

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 })

Configure the store

Create a store.ts file in the src/livestore folder. This file configures the store adapter and exports a custom hook that components will use to access the store.

The useStore() hook accepts store configuration options (schema, adapter, store ID) and returns a store instance. It suspends while the store is loading, so make sure to use a Suspense boundary to handle the loading state.

store.ts schema.ts

import { unstable_batchedUpdates as batchUpdates } from 'react-native'

import { makePersistedAdapter } from '@livestore/adapter-expo'
import { useStore } from '@livestore/react'
import { makeWsSync } from '@livestore/sync-cf/client'

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

const syncUrl = 'https://example.org/sync'

const adapter = makePersistedAdapter({
  sync: { backend: makeWsSync({ url: syncUrl }) },
})

export const useAppStore = () =>
  useStore({
    storeId: 'expo-todomvc',
    schema,
    adapter,
    batchUpdates,
    boot: (store) => {
      if (store.query(tables.todos.count()) === 0) {
        store.commit(events.todoCreated({ id: crypto.randomUUID(), text: 'Make coffee' }))
      }
    },
  })

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

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.DateFromMillis }),
    },
  }),
  uiState: State.SQLite.clientDocument({
    name: 'uiState',
    schema: Schema.Struct({ newTodoText: Schema.String, filter: Schema.Literals(['all', 'active', 'completed']) }),
    default: { id: SessionIdSymbol, value: { newTodoText: '', filter: 'all' } },
  }),
}

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.DateFromString,
    }),
  }),
  todoClearedCompleted: Events.synced({
    name: 'v1.TodoClearedCompleted',
    schema: Schema.Struct({ deletedAt: Schema.DateFromString }),
  }),
  uiStateSet: tables.uiState.set,
}

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 })

Set up the store registry

To enable store management throughout your app, create a StoreRegistry and provide it with a <StoreRegistryProvider>. The registry manages store instance lifecycles (loading, caching, disposal).

Wrap the provider in a Suspense boundary to handle the loading state for when the store is loading.

Root.tsx ListTodos.tsx NewTodo.tsx queries.ts schema.ts store.ts

import { StatusBar } from 'expo-status-bar'
import { type FC, Suspense, useState } from 'react'
import { SafeAreaView, Text, View } from 'react-native'

/* oxlint-disable react/style-prop-object */
import { StoreRegistry } from '@livestore/livestore'
import { StoreRegistryProvider } from '@livestore/react'

import { ListTodos } from './components/ListTodos.tsx'
import { NewTodo } from './components/NewTodo.tsx'

const suspenseFallback = <Text>Loading LiveStore...</Text>
const appContentStyle = { flex: 1, gap: 24, padding: 24 }
const safeAreaStyle = { flex: 1 }

const AppContent: FC = () => (
  <View style={appContentStyle}>
    <NewTodo />
    <ListTodos />
  </View>
)

export const Root: FC = () => {
  const [storeRegistry] = useState(() => new StoreRegistry())

  return (
    <SafeAreaView style={safeAreaStyle}>
      <Suspense fallback={suspenseFallback}>
        <StoreRegistryProvider storeRegistry={storeRegistry}>
          <AppContent />
        </StoreRegistryProvider>
      </Suspense>
      <StatusBar style="auto" />
    </SafeAreaView>
  )
}

import { type FC, useCallback } from 'react'
import type { TextStyle, ViewStyle } from 'react-native'
import { Button, ScrollView, Text, View } from 'react-native'

import { visibleTodos$ } from '../livestore/queries.ts'
import { events, type tables } from '../livestore/schema.ts'
import { useAppStore } from '../livestore/store.ts'

const listContainerStyle = { flex: 1, gap: 16 } satisfies ViewStyle
const listContentContainerStyle = { gap: 12 } satisfies ViewStyle
const todoContainerStyle = {
  borderRadius: 12,
  borderColor: '#d4d4d8',
  borderWidth: 1,
  padding: 16,
  gap: 8,
} satisfies ViewStyle
const todoTitleStyle = { fontSize: 16, fontWeight: '600' } satisfies TextStyle
const todoActionRowStyle = { flexDirection: 'row', gap: 12 } satisfies ViewStyle

export const ListTodos: FC = () => {
  const store = useAppStore()
  const todos = store.useQuery(visibleTodos$)

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

  const clearCompleted = useCallback(() => {
    store.commit(events.todoClearedCompleted({ deletedAt: new Date() }))
  }, [store])

  return (
    <View style={listContainerStyle}>
      <ScrollView contentContainerStyle={listContentContainerStyle}>
        {todos.map((todo) => (
          <TodoItem key={todo.id} todo={todo} onToggle={toggleTodo} />
        ))}
      </ScrollView>
      <Button title="Clear completed" onPress={clearCompleted} />
    </View>
  )
}

const TodoItem: FC<{
  todo: typeof tables.todos.Type
  onToggle: (todo: typeof tables.todos.Type) => void
}> = ({ todo, onToggle }) => {
  const store = useAppStore()
  const onTogglePress = useCallback(() => onToggle(todo), [onToggle, todo])
  const onDeletePress = useCallback(() => {
    store.commit(events.todoDeleted({ id: todo.id, deletedAt: new Date() }))
  }, [store, todo.id])

  return (
    <View style={todoContainerStyle}>
      <Text style={todoTitleStyle}>{todo.text}</Text>
      <Text>{todo.completed === true ? 'Completed' : 'Pending'}</Text>
      <View style={todoActionRowStyle}>
        <Button title={todo.completed === true ? 'Mark pending' : 'Mark done'} onPress={onTogglePress} />
        <Button title="Delete" onPress={onDeletePress} />
      </View>
    </View>
  )
}

import { type FC, useCallback } from 'react'
import { Button, TextInput, View } from 'react-native'

import { uiState$ } from '../livestore/queries.ts'
import { events } from '../livestore/schema.ts'
import { useAppStore } from '../livestore/store.ts'

const formContainerStyle = { gap: 12 }

export const NewTodo: FC = () => {
  const store = useAppStore()
  const { newTodoText } = store.useQuery(uiState$)

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

  const addSampleTodos = useCallback(() => {
    const todos = Array.from({ length: 5 }, (_, index) => ({
      id: crypto.randomUUID(),
      text: `Todo ${index + 1}`,
    }))
    store.commit(...todos.map((todo) => events.todoCreated(todo)))
  }, [store])

  return (
    <View style={formContainerStyle}>
      <TextInput value={newTodoText} onChangeText={updateText} placeholder="What needs to be done?" />
      <Button title="Add todo" onPress={createTodo} />
      <Button title="Add sample todos" onPress={addSampleTodos} />
    </View>
  )
}

import { queryDb } from '@livestore/livestore'

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

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

export const visibleTodos$ = queryDb(
  (get) => {
    const { filter } = get(uiState$)

    return tables.todos.where({
      deletedAt: null,
      completed: filter === 'all' ? undefined : filter === 'completed',
    })
  },
  { label: 'visibleTodos' },
)

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

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.DateFromMillis }),
    },
  }),
  uiState: State.SQLite.clientDocument({
    name: 'uiState',
    schema: Schema.Struct({ newTodoText: Schema.String, filter: Schema.Literals(['all', 'active', 'completed']) }),
    default: { id: SessionIdSymbol, value: { newTodoText: '', filter: 'all' } },
  }),
}

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.DateFromString,
    }),
  }),
  todoClearedCompleted: Events.synced({
    name: 'v1.TodoClearedCompleted',
    schema: Schema.Struct({ deletedAt: Schema.DateFromString }),
  }),
  uiStateSet: tables.uiState.set,
}

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 })

import { unstable_batchedUpdates as batchUpdates } from 'react-native'

import { makePersistedAdapter } from '@livestore/adapter-expo'
import { useStore } from '@livestore/react'
import { makeWsSync } from '@livestore/sync-cf/client'

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

const syncUrl = 'https://example.org/sync'

const adapter = makePersistedAdapter({
  sync: { backend: makeWsSync({ url: syncUrl }) },
})

export const useAppStore = () =>
  useStore({
    storeId: 'expo-todomvc',
    schema,
    adapter,
    batchUpdates,
    boot: (store) => {
      if (store.query(tables.todos.count()) === 0) {
        store.commit(events.todoCreated({ id: crypto.randomUUID(), text: 'Make coffee' }))
      }
    },
  })

Commit events

After setting up the registry, use the useAppStore() hook from any component to access the store and commit events.

NewTodo.tsx queries.ts schema.ts store.ts

import { type FC, useCallback } from 'react'
import { Button, TextInput, View } from 'react-native'

import { uiState$ } from '../livestore/queries.ts'
import { events } from '../livestore/schema.ts'
import { useAppStore } from '../livestore/store.ts'

const formContainerStyle = { gap: 12 }

export const NewTodo: FC = () => {
  const store = useAppStore()
  const { newTodoText } = store.useQuery(uiState$)

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

  const addSampleTodos = useCallback(() => {
    const todos = Array.from({ length: 5 }, (_, index) => ({
      id: crypto.randomUUID(),
      text: `Todo ${index + 1}`,
    }))
    store.commit(...todos.map((todo) => events.todoCreated(todo)))
  }, [store])

  return (
    <View style={formContainerStyle}>
      <TextInput value={newTodoText} onChangeText={updateText} placeholder="What needs to be done?" />
      <Button title="Add todo" onPress={createTodo} />
      <Button title="Add sample todos" onPress={addSampleTodos} />
    </View>
  )
}

import { queryDb } from '@livestore/livestore'

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

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

export const visibleTodos$ = queryDb(
  (get) => {
    const { filter } = get(uiState$)

    return tables.todos.where({
      deletedAt: null,
      completed: filter === 'all' ? undefined : filter === 'completed',
    })
  },
  { label: 'visibleTodos' },
)

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

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.DateFromMillis }),
    },
  }),
  uiState: State.SQLite.clientDocument({
    name: 'uiState',
    schema: Schema.Struct({ newTodoText: Schema.String, filter: Schema.Literals(['all', 'active', 'completed']) }),
    default: { id: SessionIdSymbol, value: { newTodoText: '', filter: 'all' } },
  }),
}

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.DateFromString,
    }),
  }),
  todoClearedCompleted: Events.synced({
    name: 'v1.TodoClearedCompleted',
    schema: Schema.Struct({ deletedAt: Schema.DateFromString }),
  }),
  uiStateSet: tables.uiState.set,
}

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 })

import { unstable_batchedUpdates as batchUpdates } from 'react-native'

import { makePersistedAdapter } from '@livestore/adapter-expo'
import { useStore } from '@livestore/react'
import { makeWsSync } from '@livestore/sync-cf/client'

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

const syncUrl = 'https://example.org/sync'

const adapter = makePersistedAdapter({
  sync: { backend: makeWsSync({ url: syncUrl }) },
})

export const useAppStore = () =>
  useStore({
    storeId: 'expo-todomvc',
    schema,
    adapter,
    batchUpdates,
    boot: (store) => {
      if (store.query(tables.todos.count()) === 0) {
        store.commit(events.todoCreated({ id: crypto.randomUUID(), text: 'Make coffee' }))
      }
    },
  })

Queries

To retrieve data from the database, define a query using queryDb from @livestore/livestore, then execute it with store.useQuery().

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

ListTodos.tsx queries.ts schema.ts store.ts

import { type FC, useCallback } from 'react'
import type { TextStyle, ViewStyle } from 'react-native'
import { Button, ScrollView, Text, View } from 'react-native'

import { visibleTodos$ } from '../livestore/queries.ts'
import { events, type tables } from '../livestore/schema.ts'
import { useAppStore } from '../livestore/store.ts'

const listContainerStyle = { flex: 1, gap: 16 } satisfies ViewStyle
const listContentContainerStyle = { gap: 12 } satisfies ViewStyle
const todoContainerStyle = {
  borderRadius: 12,
  borderColor: '#d4d4d8',
  borderWidth: 1,
  padding: 16,
  gap: 8,
} satisfies ViewStyle
const todoTitleStyle = { fontSize: 16, fontWeight: '600' } satisfies TextStyle
const todoActionRowStyle = { flexDirection: 'row', gap: 12 } satisfies ViewStyle

export const ListTodos: FC = () => {
  const store = useAppStore()
  const todos = store.useQuery(visibleTodos$)

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

  const clearCompleted = useCallback(() => {
    store.commit(events.todoClearedCompleted({ deletedAt: new Date() }))
  }, [store])

  return (
    <View style={listContainerStyle}>
      <ScrollView contentContainerStyle={listContentContainerStyle}>
        {todos.map((todo) => (
          <TodoItem key={todo.id} todo={todo} onToggle={toggleTodo} />
        ))}
      </ScrollView>
      <Button title="Clear completed" onPress={clearCompleted} />
    </View>
  )
}

const TodoItem: FC<{
  todo: typeof tables.todos.Type
  onToggle: (todo: typeof tables.todos.Type) => void
}> = ({ todo, onToggle }) => {
  const store = useAppStore()
  const onTogglePress = useCallback(() => onToggle(todo), [onToggle, todo])
  const onDeletePress = useCallback(() => {
    store.commit(events.todoDeleted({ id: todo.id, deletedAt: new Date() }))
  }, [store, todo.id])

  return (
    <View style={todoContainerStyle}>
      <Text style={todoTitleStyle}>{todo.text}</Text>
      <Text>{todo.completed === true ? 'Completed' : 'Pending'}</Text>
      <View style={todoActionRowStyle}>
        <Button title={todo.completed === true ? 'Mark pending' : 'Mark done'} onPress={onTogglePress} />
        <Button title="Delete" onPress={onDeletePress} />
      </View>
    </View>
  )
}

import { queryDb } from '@livestore/livestore'

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

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

export const visibleTodos$ = queryDb(
  (get) => {
    const { filter } = get(uiState$)

    return tables.todos.where({
      deletedAt: null,
      completed: filter === 'all' ? undefined : filter === 'completed',
    })
  },
  { label: 'visibleTodos' },
)

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

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.DateFromMillis }),
    },
  }),
  uiState: State.SQLite.clientDocument({
    name: 'uiState',
    schema: Schema.Struct({ newTodoText: Schema.String, filter: Schema.Literals(['all', 'active', 'completed']) }),
    default: { id: SessionIdSymbol, value: { newTodoText: '', filter: 'all' } },
  }),
}

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.DateFromString,
    }),
  }),
  todoClearedCompleted: Events.synced({
    name: 'v1.TodoClearedCompleted',
    schema: Schema.Struct({ deletedAt: Schema.DateFromString }),
  }),
  uiStateSet: tables.uiState.set,
}

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 })

import { unstable_batchedUpdates as batchUpdates } from 'react-native'

import { makePersistedAdapter } from '@livestore/adapter-expo'
import { useStore } from '@livestore/react'
import { makeWsSync } from '@livestore/sync-cf/client'

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

const syncUrl = 'https://example.org/sync'

const adapter = makePersistedAdapter({
  sync: { backend: makeWsSync({ url: syncUrl }) },
})

export const useAppStore = () =>
  useStore({
    storeId: 'expo-todomvc',
    schema,
    adapter,
    batchUpdates,
    boot: (store) => {
      if (store.query(tables.todos.count()) === 0) {
        store.commit(events.todoCreated({ id: crypto.randomUUID(), text: 'Make coffee' }))
      }
    },
  })

Devtools

To open the devtools, run the app and from your terminal press shift + m, then select LiveStore Devtools and press Enter.

This will open the devtools in a new tab in your default browser.

Use the devtools to inspect the state of your LiveStore database, execute events, track performance, and more.

Database location

With Expo Go

To open the database in Finder, run the following command in your terminal:

open $(find $(xcrun simctl get_app_container booted host.exp.Exponent data) -path "*/Documents/ExponentExperienceData/*livestore-expo*" -print -quit)/SQLite

With development builds

For development builds, the app SQLite database is stored in the app’s Library directory.

Example: /Users/<USERNAME>/Library/Developer/CoreSimulator/Devices/<DEVICE_ID>/data/Containers/Data/Application/<APP_ID>/Documents/SQLite/app.db

To open the database in Finder, run the following command in your terminal:

open $(xcrun simctl get_app_container booted [APP_BUNDLE_ID] data)/Documents/SQLite

Replace [APP_BUNDLE_ID] with your app’s bundle ID. e.g. dev.livestore.livestore-expo.

Further notes

• LiveStore doesn’t yet support Expo Web (see #130)