Project setup

1. Copy the source/ directory into your project root (or reference the packages directly from npm — the published packages are what source/packages/ builds).

2. Start a local Postgres + Electric instance:

   docker compose -f source/.support/docker-compose.yml up
   

   Electric listens on http://localhost:3000 by default.

3. Set environment variables in .env:

   DATABASE_URL=postgresql://postgres:password@localhost:5432/mydb
   ELECTRIC_URL=http://localhost:3000
   AUTH_SECRET=your-jwt-secret
   API_URL=http://localhost:4000
   

4. Wire up tsconfig.json to include path aliases if you copy source packages locally:

   {
     "extends": "./source/tsconfig.base.json",
     "compilerOptions": {
       "paths": {
         "@electric-sql/client": ["./source/packages/typescript-client/src"]
       }
     }
   }
   

5. Enable logical replication on Postgres:

   ALTER SYSTEM SET wal_level = logical;
   

   Then restart Postgres.

6. Install monorepo deps if working inside source/ directly:

   corepack enable
   pnpm install
   

Public API

ShapeStream

import { ShapeStream, ShapeStreamOptions } from '@electric-sql/client'

const stream = new ShapeStream({
  url: 'http://localhost:3000/v1/shape',
  params: { table: 'items', where: 'status = \'active\'' },
  onError: async (error: FetchError | Error) => {
    // return new config to retry with different headers, or void to stop
  },
})

ShapeStream opens a long-poll HTTP connection to the Electric sync endpoint and emits change messages for the specified table/shape. Use it when you need a low-level stream of row operations (inserts, updates, deletes) without any React dependency. The onError callback lets you refresh auth tokens transparently — returning a new config object resumes streaming without dropping state.

Shape

import { Shape, ShapeStream } from '@electric-sql/client'

const stream = new ShapeStream({ url: '...', params: { table: 'items' } })
const shape = new Shape(stream)

const unsubscribe = shape.subscribe(({ rows }) => {
  console.log('current rows:', rows)
})

Shape materializes a ShapeStream into an in-memory collection of rows and exposes a subscribe callback that fires on every change. Use it when you want a maintained view of the current dataset without a framework integration. Call unsubscribe() to stop listening.

FetchError

import { FetchError } from '@electric-sql/client'

stream = new ShapeStream({
  url: '...',
  params: { table: 'items' },
  onError: async (error) => {
    if (error instanceof FetchError) {
      if (error.status === 401) {
        const newConfig = await refreshToken()
        return newConfig  // resume with new headers
      }
      if (error.status >= 400 && error.status < 500) {
        return  // stop stream on unrecoverable client errors
      }
    }
    return {}  // retry same config on network errors
  },
})

FetchError is thrown when the Electric HTTP endpoint returns a non-2xx status. Its .status property gives you the HTTP status code. It is the primary mechanism for distinguishing auth failures (401/403) from server errors (5xx, which Electric retries automatically) and permanent client errors (other 4xx).

Working examples

Scenario - Basic shape subscription in Node.js

Sync all rows from a Postgres table into memory and log changes as they arrive. No React required.

import { Shape, ShapeStream, FetchError } from '@electric-sql/client'

const stream = new ShapeStream({
  url: process.env.ELECTRIC_URL + '/v1/shape',
  params: { table: 'orders' },
  onError: async (error) => {
    if (error instanceof FetchError && error.status === 401) {
      return { headers: { Authorization: 'Bearer ' + await getNewToken() } }
    }
    return {}
  },
})

const shape = new Shape(stream)

shape.subscribe(({ rows }) => {
  console.log(`Total orders in sync: ${rows?.length ?? 0}`)
  rows?.forEach((row) => console.log(row))
})

Scenario - Gatekeeper auth with token refresh

Fetch shape config from a backend gatekeeper endpoint that issues signed JWTs, then stream through a proxy. Transparently refresh on 401.

import { ShapeStream, Shape, FetchError } from '@electric-sql/client'

const API_URL = process.env.API_URL || 'http://localhost:4000'

async function fetchConfig() {
  const resp = await fetch(`${API_URL}/gatekeeper/items`, { method: 'POST' })
  return resp.json() // { url, headers }
}

const config = await fetchConfig()

const stream = new ShapeStream({
  ...config,
  onError: async (error) => {
    if (error instanceof FetchError) {
      if (error.status === 401 || error.status === 403) {
        return await fetchConfig()  // rotate token, keep streaming
      }
      if (error.status >= 400 && error.status < 500) {
        console.error(`Stopping: ${error.status}`)
        return
      }
    }
    return {}
  },
})

const shape = new Shape(stream)
shape.subscribe(({ rows }) => console.log('rows:', rows?.length))

Scenario - Filtered shape with where clause

Sync only a subset of rows matching a Postgres WHERE expression. Useful for per-user or per-tenant data isolation.

import { ShapeStream, Shape } from '@electric-sql/client'

const userId = 'user_abc123'

const stream = new ShapeStream({
  url: 'http://localhost:3000/v1/shape',
  params: {
    table: 'messages',
    where: `recipient_id = '${userId}'`,
    columns: 'id,body,inserted_at',
  },
})

const shape = new Shape(stream)

shape.subscribe(({ rows }) => {
  const messages = rows ?? []
  messages.sort((a, b) =>
    new Date(a.inserted_at).getTime() - new Date(b.inserted_at).getTime()
  )
  console.log('Messages for user:', messages)
})

File walkthrough

• .changeset/ - Each .md file describes a pending version bump and changelog entry for a package in packages/; consumed by @changesets/cli during release.
• .claude/commands/pr-review.md - Prompt template for automated PR review via Claude; not runtime code.
• .github/workflows/ - Full CI matrix: Elixir sync service tests, TypeScript tests, Docker image builds, integration tests, benchmark runs, and example deployments.
• .support/docker-compose.yml - Reference Docker Compose configuration to run Postgres with logical replication and the Electric sync service locally.
• examples/burn/ - Real-time multi-user thread/messaging app using @tanstack/react-db live queries backed by Electric shapes.
• examples/gatekeeper-auth/ - Demonstrates backend-issued signed JWT tokens for shape-level auth, with a Deno edge proxy and a TypeScript client showing token refresh.
• examples/linearlite/ - Linear-clone project management app using PGlite with Electric sync and useLiveQuery from @electric-sql/pglite-react.
• packages/ - Source for all published npm packages including @electric-sql/client, @electric-sql/react, @electric-sql/pglite-react.
• scripts/ - Monorepo maintenance utilities (release scripts, workspace helpers).
• tsconfig.base.json / tsconfig.build.json - Shared compiler options inherited by all packages.

Common pitfalls and fixes

• Logical replication not enabled: Electric will fail to connect if wal_level is not logical. Fix: ALTER SYSTEM SET wal_level = logical; then restart Postgres.
• offset=-1 required on first request: The HTTP API requires ?offset=-1 to signal an initial snapshot. Without it Electric returns 400. Fix: always pass offset: -1 or use ShapeStream which handles this automatically.
• onError must return a config object or void: Returning undefined explicitly does not stop the stream in all client versions — return void (no return statement) to stop, or {} to retry. Fix: follow the pattern in examples/gatekeeper-auth/client/index.ts exactly.
• 5xx errors are retried automatically: Do not implement your own retry loop for server errors; Electric's client already has exponential backoff. Wrapping it causes duplicate subscriptions.
• ESM/CJS interop: @electric-sql/client ships ESM. If your bundler or Jest config uses moduleResolution: node, add it to transformIgnorePatterns or switch to moduleResolution: bundler. Fix: set "moduleResolution": "bundler" in tsconfig.json.
• Docker image pull fails in CI: The Electric Docker image is electricsql/electric. Pin a specific tag (e.g., electricsql/electric:1.0.0) rather than latest to avoid unexpected breaking changes in pipelines.

Vibe-coding prompt template

I have the ElectricSQL monorepo checked out at `./source/` and its
integration guide at `./source/USAGE.md`. The upstream package is
`@electric-sql/client` (and optionally `@electric-sql/react`).

My project is a [describe your stack: e.g., Next.js 14 app / Express API /
Deno edge function] that needs real-time sync from a Postgres table called
`[your_table]`.

Please help me integrate ElectricSQL step by step:

1. Read `./source/USAGE.md` for setup instructions, real export names, and
   working code examples.
2. Add the required npm dependencies to my `package.json`.
3. Create a `ShapeStream` pointed at my Electric instance
   (`ELECTRIC_URL` from env) syncing the `[your_table]` table, filtered
   by `[your where clause if any]`.
4. Wrap it in a `Shape` and subscribe to row changes, logging results.
5. If I need auth, implement the gatekeeper pattern from
   `source/examples/gatekeeper-auth/client/index.ts` with token refresh
   in `onError`.
6. Wire everything into my existing [component / route / service] at
   `[path to your file]`.

Use only the APIs visible in `./source/USAGE.md`. Do not invent method
names. Show me the final file contents.

License and credit

ElectricSQL is released under the Apache 2.0 License (see source/LICENSE). Source repository and upstream project: https://github.com/electric-sql/electric. Published npm packages live under the @electric-sql scope on npmjs.com.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.

Automation, Utilities & Developer Tools

무료