local-village

A local-first, offline-first React library for building reliable applications with seamless sync.

Features

• Offline-First: All data operations work instantly, even without network connectivity
• Automatic Sync: Changes sync automatically when online, with conflict resolution
• Real-time Updates: WebSocket-based real-time collaboration with presence tracking
• Type-Safe: Full TypeScript support with strict typing
• React Hooks: Intuitive hooks-based API for React applications
• IndexedDB Storage: Persistent local storage using IndexedDB
• Conflict Resolution: Built-in strategies with custom resolution support
• DevTools: Built-in debugging panel for development

Installation

npm install local-village
# or
yarn add local-village
# or
pnpm add local-village

Requirements

• React 18+
• Modern browser with IndexedDB support

Quick Start

1. Wrap Your App

import { LocalVillageProvider } from 'local-village'

function App() {
  return (
    <LocalVillageProvider
      config={{
        database: { name: 'my-app' },
        sync: {
          serverUrl: 'http://localhost:3000',
          autoSync: true,
        },
      }}
    >
      <YourApp />
    </LocalVillageProvider>
  )
}

2. Query Data

import { useLocalQuery } from 'local-village'

function TodoList() {
  const { data: todos, loading, error } = useLocalQuery('todos', {
    where: { completed: false },
    orderBy: { field: 'createdAt', direction: 'desc' },
  })

  if (loading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  return (
    <ul>
      {todos.map((todo) => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  )
}

3. Mutate Data

import { useLocalMutation } from 'local-village'

function AddTodo() {
  const { create } = useLocalMutation('todos')

  const handleAdd = async () => {
    await create({
      title: 'New todo',
      completed: false,
      createdAt: Date.now(),
    })
  }

  return <button onClick={handleAdd}>Add Todo</button>
}

React Hooks

| Hook | Description | |------|-------------| | useLocalQuery | Query data with filtering, sorting, and pagination | | useLocalDocument | Get a single document by ID | | useLocalMutation | Create, update, and delete operations | | useLocalState | Persistent local state (like useState but persisted) | | useSyncStatus | Monitor sync state and pending operations | | useConflicts | Handle and resolve sync conflicts | | useNetworkStatus | Monitor online/offline status | | useRealtime | WebSocket connection and subscriptions | | usePresence | Real-time presence in rooms |

Offline-First Architecture

┌─────────────────────────────────────────────────────────┐
│                        Client                            │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
│  │  React App  │───▶│    Store    │───▶│  IndexedDB  │  │
│  └─────────────┘    └─────────────┘    └─────────────┘  │
│         │                  │                             │
│         │                  ▼                             │
│         │           ┌─────────────┐                      │
│         └──────────▶│ Sync Engine │◀──── WebSocket ────┤
│                     └─────────────┘                      │
└─────────────────────────────────────────────────────────┘

All data is stored locally in IndexedDB first, making reads and writes instant. Changes sync to the server when online.

DevTools

Add the DevTools panel for debugging:

import { DevToolsProvider, DevToolsPanel } from 'local-village'

function App() {
  return (
    <LocalVillageProvider config={...}>
      <DevToolsProvider>
        <YourApp />
        {process.env.NODE_ENV !== 'production' && <DevToolsPanel />}
      </DevToolsProvider>
    </LocalVillageProvider>
  )
}

Server Package

For the server-side sync endpoint, install local-village-server:

npm install local-village-server

Documentation

• Client API Reference
• Real-time Guide
• Sync & Conflicts
• DevTools Guide

License

MIT