Effect

LiveStore itself is built on top of Effect which is a powerful library to write production-grade TypeScript code. It’s also possible (and recommended) to use Effect directly in your application code.

Schema

LiveStore uses the Effect Schema library to define schemas for the following:

• Read model table column definitions
• Event event payloads definitions
• Query response types

For convenience, LiveStore re-exports the Schema module from the effect package, which is the same as if you’d import it via import { Schema } from 'effect' directly.

Equal and Hash Traits

LiveStore’s reactive primitives (LiveQueryDef and SignalDef) implement Effect’s Equal and Hash traits, enabling efficient integration with Effect’s data structures and collections.

Effect Atom Integration

LiveStore integrates seamlessly with Effect Atom for reactive state management in React applications. This provides a powerful combination of Effect’s functional programming capabilities with LiveStore’s event sourcing and CQRS patterns.

Effect Atom is an external package developed by Tim Smart that provides a more Effect-idiomatic alternative to the @livestore/react package. While @livestore/react offers a straightforward React integration, Effect Atom leverages Effect API/patterns throughout, making it a natural choice for applications already using Effect.

Installation

pnpm install @effect-atom/atom-livestore @effect-atom/atom-react

Store Creation

Create a LiveStore-backed atom store with persistence and worker support using the AtomLivestore.Tag pattern:

atoms.ts

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

import { AtomLivestore } from '@effect-atom/atom-livestore'
import { makePersistedAdapter } from '@livestore/adapter-web'
import LiveStoreSharedWorker from '@livestore/adapter-web/shared-worker?sharedworker'
import LiveStoreWorker from '@livestore/adapter-web/worker?worker'
import { unstable_batchedUpdates } from 'react-dom'
import { schema } from './schema.ts'

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

// Create a persistent adapter with OPFS storage
const adapter = makePersistedAdapter({
  storage: { type: 'opfs' },
  worker: LiveStoreWorker,
  sharedWorker: LiveStoreSharedWorker,
})

// Define the store as a service tag
export class StoreTag extends AtomLivestore.Tag<StoreTag>()('StoreTag', {
  schema,
  storeId: 'default',
  adapter,
  batchUpdates: unstable_batchedUpdates, // React batching for performance
}) {}

The StoreTag class provides the following static methods:

• StoreTag.runtime - Access to Effect runtime
• StoreTag.commit - Commit events to the store
• StoreTag.store - Access store with Effect
• StoreTag.storeUnsafe - Direct store access when store is already loaded (synchronous)
• StoreTag.makeQuery - Create query atoms with Effect
• StoreTag.makeQueryUnsafe - Create query atoms without Effect

Defining Query Atoms

Create reactive query atoms that automatically update when the underlying data changes:

queries.ts

import { Atom } from '@effect-atom/atom'
import { queryDb, sql } from '@livestore/livestore'
import { Schema } from 'effect'
import { StoreTag } from './atoms.ts'

// User schema for type safety
const User = Schema.Struct({
  id: Schema.String,
  name: Schema.String,
  isActive: Schema.Boolean,
})

const Product = Schema.Struct({
  id: Schema.String,
  name: Schema.String,
  createdAt: Schema.DateTimeUtc,
})

// Search term atom for dynamic queries
export const searchTermAtom = Atom.make<string>('')

// Re-export from utils for convenience
export { usersQueryAtom as usersAtom } from './utils.ts'

// Query with SQL
export const activeUsersAtom = StoreTag.makeQuery(
  queryDb({
    query: sql`SELECT * FROM users WHERE isActive = true ORDER BY name`,
    schema: Schema.Array(User),
  }),
)

// Static query example - dynamic queries would need a different approach
// For dynamic queries, you'd typically use a derived atom that depends on searchTermAtom
export const searchResultsAtom = StoreTag.makeQuery(
  queryDb({
    query: sql`SELECT * FROM products ORDER BY createdAt DESC`,
    schema: Schema.Array(Product),
  }),
)

Using Queries in React Components

Access query results in React components with the useAtomValue hook. When using StoreTag.makeQuery (non-unsafe API), the result is wrapped in a Result type for proper loading and error handling:

UserList.tsx

import { Result, useAtomValue } from '@effect-atom/atom-react'
import { activeUsersAtom } from './queries.ts'

export function UserList() {
  const users = useAtomValue(activeUsersAtom)

  return Result.builder(users)
    .onInitial(() => <div>Loading users...</div>)
    .onSuccess((users) => (
      <ul>
        {users.map((user) => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    ))
    .onDefect((error: any) => <div>Error: {error.message}</div>)
    .render()
}

Integrating Effect Services

Combine Effect services with LiveStore operations using the store’s runtime:

services.tsx

import { useAtomSet } from '@effect-atom/atom-react'
import { Context, Effect } from 'effect'
import { StoreTag } from './atoms.ts'
import { events } from './schema.ts'

// Example service definition
export class MyService extends Context.Tag('MyService')<
  MyService,
  {
    processItem: (name: string) => Effect.Effect<{
      name: string
      metadata: Record<string, unknown>
    }>
  }
>() {}

// Use the commit hook for event handling
export const useCommit = () => useAtomSet(StoreTag.commit)

// Simple commit example
export const createItemAtom = StoreTag.runtime.fn<string>()((itemName, get) => {
  return Effect.sync(() => {
    const store = get(StoreTag.storeUnsafe)
    if (store) {
      store.commit(
        events.itemCreated({
          id: crypto.randomUUID(),
          name: itemName,
          metadata: { createdAt: new Date().toISOString() },
        }),
      )
    }
  })
})

// Use in a React component
export function CreateItemButton() {
  const createItem = useAtomSet(createItemAtom)

  const handleClick = () => {
    createItem('New Item')
  }

  return (
    <button type="button" onClick={handleClick}>
      Create Item
    </button>
  )
}

Advanced Patterns

Optimistic Updates

Combine local state with LiveStore for optimistic UI updates. When using StoreTag.makeQueryUnsafe, the data is directly available:

optimistic.ts

import { Atom } from '@effect-atom/atom'
import { pendingTodosAtom, todosQueryUnsafeAtom } from '../store-setup/utils.ts'

// Combine real and pending todos for optimistic UI
export const optimisticTodoAtom = Atom.make((get) => {
  const todos = get(todosQueryUnsafeAtom) // Direct array, not wrapped in Result
  const pending = get(pendingTodosAtom)

  return [...(todos || []), ...pending]
})

Derived State

Create computed atoms based on LiveStore queries. When using the non-unsafe API, handle the Result type:

derived.ts

import { Atom } from '@effect-atom/atom'
import { Result } from '@effect-atom/atom-react'
import { todosQueryAtom } from '../store-setup/utils.ts'

// Derive statistics from todos
export const todoStatsAtom = Atom.make((get) => {
  const todos = get(todosQueryAtom) // Result wrapped

  return Result.map(todos, (todoList) => ({
    total: todoList.length,
    completed: todoList.filter((t) => t.completed).length,
    pending: todoList.filter((t) => !t.completed).length,
  }))
})

Batch Operations

Perform multiple commits efficiently (commits are synchronous):

batch.ts

import { Effect } from 'effect'
import { StoreTag } from '../store-setup/atoms.ts'
import { events } from '../store-setup/schema.ts'

// Bulk update atom for batch operations
export const bulkUpdateAtom = StoreTag.runtime.fn<string[]>()(
  Effect.fn(function* (ids, get) {
    const store = get(StoreTag.storeUnsafe)
    if (!store) return

    // Commit multiple events synchronously
    for (const id of ids) {
      store.commit(events.itemUpdated({ id, status: 'processed' }))
    }
  }),
)

Best Practices

1. Use StoreTag.makeQuery for queries: This ensures proper Effect integration and error handling
2. Leverage Effect services: Integrate business logic through Effect services for better testability
3. Handle loading states: Use Result.builder pattern for consistent loading/error UI
4. Batch React updates: Always provide batchUpdates for better performance
5. Label queries: Add descriptive labels to queries for better debugging
6. Type safety: Let TypeScript infer types from schemas rather than manual annotations

Real-World Example

For a comprehensive example of LiveStore with Effect Atom in action, check out Cheffect - a recipe management application that demonstrates:

• Complete Effect service integration
• AI-powered recipe extraction using Effect services
• Complex query patterns with search and filtering
• Worker-based persistence with OPFS
• Production-ready error handling and logging