Store

The Store is the most common way to interact with LiveStore from your application code. It provides a way to query data, commit events, and subscribe to data changes.

Creating a store

For how to create a store in React, see the React integration docs. The following example shows how to create a store manually:

create-store.ts schema.ts

import { makeAdapter } from '@livestore/adapter-node'
import { createStorePromise } from '@livestore/livestore'

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

const adapter = makeAdapter({
  storage: { type: 'fs' },
  // sync: { backend: makeWsSync({ url: '...' }) },
})

export const bootstrap = async () => {
  const store = await createStorePromise({
    schema,
    adapter,
    storeId: 'some-store-id',
  })

  return store
}

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

const tables = {
  todos: State.SQLite.table({
    name: 'todos',
    columns: {
      id: State.SQLite.text({ primaryKey: true }),
      text: State.SQLite.text(),
      completed: State.SQLite.boolean({ default: false }),
    },
  }),
} as const

const events = {
  todoCreated: Events.synced({
    name: 'v1.TodoCreated',
    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
  }),
} as const

const materializers = State.SQLite.materializers(events, {
  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
    tables.todos.insert({ id, text, completed: false }),
  ),
})

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

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

Using a store

Querying data

query-data.ts schema.ts

import type { Store } from '@livestore/livestore'
import { storeTables } from './schema.ts'

declare const store: Store

const todos = store.query(storeTables.todos)
console.log(todos)

import type { Store } from '@livestore/livestore'

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

declare const store: Store

const todos = store.query(storeTables.todos)
console.log(todos)

Subscribing to data

subscribe.ts schema.ts

import type { Store } from '@livestore/livestore'

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

declare const store: Store

const unsubscribe = store.subscribe(storeTables.todos, (todos) => {
  console.log(todos)
})

unsubscribe()

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

const tables = {
  todos: State.SQLite.table({
    name: 'todos',
    columns: {
      id: State.SQLite.text({ primaryKey: true }),
      text: State.SQLite.text(),
      completed: State.SQLite.boolean({ default: false }),
    },
  }),
} as const

const events = {
  todoCreated: Events.synced({
    name: 'v1.TodoCreated',
    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
  }),
} as const

const materializers = State.SQLite.materializers(events, {
  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
    tables.todos.insert({ id, text, completed: false }),
  ),
})

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

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

Committing events

commit-event.ts schema.ts

import type { Store } from '@livestore/livestore'

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

declare const store: Store

store.commit(storeEvents.todoCreated({ id: '1', text: 'Buy milk' }))

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

const tables = {
  todos: State.SQLite.table({
    name: 'todos',
    columns: {
      id: State.SQLite.text({ primaryKey: true }),
      text: State.SQLite.text(),
      completed: State.SQLite.boolean({ default: false }),
    },
  }),
} as const

const events = {
  todoCreated: Events.synced({
    name: 'v1.TodoCreated',
    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
  }),
} as const

const materializers = State.SQLite.materializers(events, {
  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
    tables.todos.insert({ id, text, completed: false }),
  ),
})

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

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

Streaming events

Currently only events confirmed by the sync backend are supported.

stream-events.ts

import type { Store } from '@livestore/livestore'

declare const store: Store

// Run once
for await (const event of store.events()) {
  console.log('event from leader', event)
}

// Continuos stream
const iterator = store.events()[Symbol.asyncIterator]()
try {
  while (true) {
    const { value, done } = await iterator.next()
    if (done === true) break
    console.log('event from stream:', value)
  }
} finally {
  await iterator.return?.()
}

Shutting down a store

LiveStore provides two APIs for shutting down a store:

shutdown.ts

import type { Store } from '@livestore/livestore'

declare const store: Store

const effectShutdown = Effect.gen(function* () {
  yield* Effect.log('Shutting down store')
  yield* store.shutdown()
})

const shutdownWithPromise = async () => {
  await store.shutdownPromise()
}

Effect integration

For applications using Effect, LiveStore provides a type-safe way to access stores through the Effect layer system via makeStoreContext().

Creating a typed store context

Use makeStoreContext() to create a typed context that preserves your schema types:

make-store-context.ts schema.ts

// Define a typed store context with your schema
export const TodoStore = Store.Tag(schema, 'todos')

// Create a layer to initialize the store
const adapter = makeAdapter({ storage: { type: 'fs' } })

  adapter,
  batchUpdates: (cb) => cb(), // For Node.js; use React's unstable_batchedUpdates in React apps
})


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

const tables = {

// Define a typed store context with your schema
export const TodoStore = Store.Tag(schema, 'todos')

// Create a layer to initialize the store
const adapter = makeAdapter({ storage: { type: 'fs' } })

export const TodoStoreLayer = TodoStore.layer({
  adapter,
  batchUpdates: (cb) => cb(), // For Node.js; use React's unstable_batchedUpdates in React apps
})

The factory takes your schema type as a generic parameter and returns a StoreContext with:

• Tag - Context tag for dependency injection
• Layer - Creates a layer that initializes the store
• DeferredTag - For async initialization patterns
• DeferredLayer - Layer providing the deferred context
• fromDeferred - Layer that waits for deferred initialization

Using the store in Effect services

Access the store in Effect code with full type safety and autocomplete:

usage-in-service.ts make-store-context.ts schema.ts

// Define a typed store context with your schema
export const TodoStore = Store.Tag(schema, 'todos')

// Create a layer to initialize the store
const adapter = makeAdapter({ storage: { type: 'fs' } })

  adapter,
  batchUpdates: (cb) => cb(), // For Node.js; use React's unstable_batchedUpdates in React apps
})


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

const tables = {
  todos: State.SQLite.table({
    name: 'todos',
    columns: {
      id: State.SQLite.text({ primaryKey: true }),
      text: State.SQLite.text(),
      completed: State.SQLite.boolean({ default: false }),
    },
  }),
} as const

const events = {
  todoCreated: Events.synced({
    name: 'v1.TodoCreated',
    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),

// Access the store in Effect code with full type safety
const _todoService = Effect.gen(function* () {
  // Yield the store directly (it's a Context.Service)
  const { store } = yield* TodoStore

  // Query with autocomplete for tables

  // Commit events
  store.commit(storeEvents.todoCreated({ id: '1', text: 'Buy milk' }))

  return todos
})

// Or use static accessors for a more functional style
const _todoServiceAlt = Effect.gen(function* () {
  // Query using static accessor
  const todos = yield* TodoStore.query(storeTables.todos.select())

// Define a typed store context with your schema
export const TodoStore = Store.Tag(schema, 'todos')

// Create a layer to initialize the store
const adapter = makeAdapter({ storage: { type: 'fs' } })

export const TodoStoreLayer = TodoStore.layer({
  adapter,
  batchUpdates: (cb) => cb(), // For Node.js; use React's unstable_batchedUpdates in React apps
})

Layer composition

Compose store layers with your application services:

layer-composition.ts make-store-context.ts schema.ts

// Define a typed store context with your schema
export const TodoStore = Store.Tag(schema, 'todos')

// Create a layer to initialize the store
const adapter = makeAdapter({ storage: { type: 'fs' } })

  adapter,
  batchUpdates: (cb) => cb(), // For Node.js; use React's unstable_batchedUpdates in React apps
})


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

const tables = {
  todos: State.SQLite.table({
    name: 'todos',
    columns: {
      id: State.SQLite.text({ primaryKey: true }),
      text: State.SQLite.text(),
      completed: State.SQLite.boolean({ default: false }),
    },
  }),
} as const

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 }),
  }),
} as const

const materializers = State.SQLite.materializers(events, {
  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
    tables.todos.insert({ id, text, completed: false }),
  ),

// Define services that depend on the store
class TodoService extends Context.Service<
  TodoService,
  {
    createTodo: (id: string, text: string) => Effect.Effect<void>
    completeTodo: (id: string) => Effect.Effect<void>
>()('TodoService') {
  static readonly layer = Layer.effect(
    TodoService,
    Effect.gen(function* () {
      const { store } = yield* TodoStore

      const createTodo = (id: string, text: string) =>
        Effect.sync(() => store.commit(storeEvents.todoCreated({ id, text })))

      const completeTodo = (id: string) => Effect.sync(() => store.commit(storeEvents.todoCompleted({ id })))

// Define a typed store context with your schema
export const TodoStore = Store.Tag(schema, 'todos')

// Create a layer to initialize the store
const adapter = makeAdapter({ storage: { type: 'fs' } })

export const TodoStoreLayer = TodoStore.layer({
  adapter,
  batchUpdates: (cb) => cb(), // For Node.js; use React's unstable_batchedUpdates in React apps
})

Multiple stores with Effect

Each store gets a unique context tag, allowing multiple stores in the same Effect context:

multiple-stores.ts schema.ts

// Define multiple typed store contexts
const MainStore = Store.Tag(mainSchema, 'main')
const SettingsStore = Store.Tag(settingsSchema, 'settings')

// Each store has its own layer
const adapter = makeAdapter({ storage: { type: 'fs' } })

const MainStoreLayer = MainStore.layer({ adapter, batchUpdates: (cb) => cb() })
const SettingsStoreLayer = SettingsStore.layer({ adapter, batchUpdates: (cb) => cb() })

// Compose layers together

// Both stores available in Effect code
const _program = Effect.gen(function* () {
  const { store: mainStore } = yield* MainStore
  const { store: settingsStore } = yield* SettingsStore

  // Each store is independently typed
  return { mainStore, settingsStore }
})


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

const tables = {
  todos: State.SQLite.table({
    name: 'todos',
    columns: {
      id: State.SQLite.text({ primaryKey: true }),
      text: State.SQLite.text(),

// Define multiple typed store contexts
const MainStore = Store.Tag(mainSchema, 'main')
const SettingsStore = Store.Tag(settingsSchema, 'settings')

// Each store has its own layer
const adapter = makeAdapter({ storage: { type: 'fs' } })

const MainStoreLayer = MainStore.layer({ adapter, batchUpdates: (cb) => cb() })
const SettingsStoreLayer = SettingsStore.layer({ adapter, batchUpdates: (cb) => cb() })

// Compose layers together
const _AllStoresLayer = Layer.mergeAll(MainStoreLayer, SettingsStoreLayer)

// Both stores available in Effect code
const _program = Effect.gen(function* () {
  const { store: mainStore } = yield* MainStore
  const { store: settingsStore } = yield* SettingsStore

  // Each store is independently typed
  return { mainStore, settingsStore }
})

For more Effect patterns including Effect Atom integration, see the Effect patterns page.

Multiple stores

You can create and use multiple stores in the same app. This can be useful when breaking up your data model into smaller pieces.

Sync Status

LiveStore provides APIs to monitor the synchronization status between the client session and the leader thread. This is useful for displaying sync indicators or performing health checks.

SyncStatus type

type SyncStatus = {
  localHead: string      // e.g., "e5.2" or "e5.2r1"
  upstreamHead: string   // e.g., "e3"
  pendingCount: number   // Number of events pending sync
  isSynced: boolean      // true when pendingCount === 0
}

store.syncStatus()

Returns the current sync status synchronously.

const status = store.syncStatus()
if (!status.isSynced) {
  console.log(`${status.pendingCount} events pending sync`)
}

store.subscribeSyncStatus(callback)

Subscribes to sync status changes. The callback is invoked immediately with the current status and whenever the sync state changes.

const unsubscribe = store.subscribeSyncStatus((status) => {
  updateUI(status.isSynced ? 'Synced' : 'Syncing...')
})

// Later, stop listening
unsubscribe()

store.syncStatusStream()

Returns an Effect Stream of sync status updates. For Effect-based workflows.

import { Effect, Stream } from 'effect'

store.syncStatusStream().pipe(
  Stream.tap((status) => Effect.log(`Sync: ${status.isSynced}`)),
  Stream.runDrain,
)

For React, see store.useSyncStatus().

Development/debugging helpers

A store instance also exposes a _dev property that contains some helpful methods for development. For convenience you can access a store on globalThis/window like via __debugLiveStore.default._dev (default is the store id):

// Download the SQLite database
__debugLiveStore.default._dev.downloadDb()

// Download the eventlog database
__debugLiveStore.default._dev.downloadEventlogDb()

// Reset the store
__debugLiveStore.default._dev.hardReset()

// See the current sync state
__debugLiveStore.default._dev.syncStates()