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'


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

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* store.shutdown()
})

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

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.

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