Svelte Electric Through DB

A robust, offline-first synchronization library for SvelteKit using ElectricSQL, PGlite, and Yjs. This library implements the "Through the Database" pattern, where Yjs updates are persisted to a local PGlite database and synced via ElectricSQL.

Features

• Offline-First: All writes go to the local PGlite database immediately.
• CRDT Synchronization: Uses Yjs for automatic conflict resolution.
• Bring Your Own Auth (BYOA): Plug in any authentication provider.
• Full History: Preserves document history with automatic compaction.
• SvelteKit Ready: Designed for seamless integration with SvelteKit.

Installation

npm install @trokster/svelte-electric-through-db

Usage

1. Client-Side Setup

Initialize the ElectricClient in your Svelte component or store.

import { ElectricClient } from '@trokster/svelte-electric-through-db';

const client = new ElectricClient({
    dbPath: 'idb://my-app-db',
    electricService: import.meta.env.VITE_ELECTRIC_SERVICE,
    docId: 'my-document-id',
    ownerId: 'current-user-id',
    authProvider: async () => {
        // Fetch your auth token here
        const res = await fetch('/api/auth/token');
        const { token } = await res.json();
        return token;
    }
});

await client.init();

// Use Yjs doc
const ytext = client.doc.getText('content');

2. Server-Side Setup

This library provides helpers to set up the necessary database schema and endpoints.

Database Schema (src/lib/server/db/init.ts):

import { initializeSchema } from '@trokster/svelte-electric-through-db/server';

// Run this on server startup or migration
await initializeSchema(pool, 'my_custom_schema'); // Optional: defaults to 'public'

Auth Token Helper (src/routes/api/auth/token/+server.ts):

import { createElectricToken } from '@trokster/svelte-electric-through-db/server';
import { json } from '@sveltejs/kit';

export async function GET({ locals }) {
    const token = createElectricToken(locals.user.id);
    return json({ token });
}

Database Selection

• Server-Side: The database is determined by the pg.Pool or Client you pass to initializeSchema and handlePushRequest. Configure your connection string to point to the desired database (e.g., postgres://user:pass@host:5432/my_database).
• Client-Side: The local database name is set via the dbPath option in ElectricClient (e.g., idb://my-local-db).

Environment Variables

The library uses the following environment variables if not provided explicitly:

• ELECTRIC_TOKEN_SECRET: Used by createElectricToken to sign tokens.
• AUTH_JWT_KEY: Used by verifyAuthToken to verify session tokens (if using the helper).

Ensure these are set in your server environment (e.g., .env file). 2. Sync: The SyncManager pushes these updates to your API and pulls changes from ElectricSQL. 3. Conflict Resolution: Yjs handles merging updates from different clients.