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.

Hướng dẫn cài đặt đầy đủ và prompt tích hợp sẽ mở khóa sau khi mua.

Electric: Real-Time Postgres Sync Engine

Automation, Utilities & Developer Tools

Miễn phí