TypeScript client for ElectricSQL

Real-time Postgres sync for modern apps.

Electric provides an HTTP interface to Postgres to enable a massive number of clients to query and get real-time updates to subsets of the database, called Shapes. In this way, Electric turns Postgres into a real-time database.

The TypeScript client helps ease reading Shapes from the HTTP API in the browser and other JavaScript environments, such as edge functions and server-side Node/Bun/Deno applications. It supports both fine-grained and coarse-grained reactivity patterns — you can subscribe to see every row that changes, or you can just subscribe to get the whole shape whenever it changes.

Install

The client is published on NPM as @electric-sql/next:

1npm i @electric-sql/next

How to use

The client exports a ShapeStream class for getting updates to shapes on a row-by-row basis as well as a Shape class for getting updates to the entire shape.

ShapeStream

1import { ShapeStream } from 'electric-sql'
2
3// Passes subscribers rows as they're inserted, updated, or deleted
4const stream = new ShapeStream({
5  url: `${BASE_URL}/v1/shape/foo`,
6})
7
8stream.subscribe(messages => {
9  // messages is an array with one or more row updates
10})

Shape

1import { ShapeStream, Shape } from 'electric-sql'
2
3const stream = new ShapeStream({
4  url: `${BASE_URL}/v1/shape/foo`,
5})
6const shape = new Shape(stream)
7
8// Returns promise that resolves with the latest shape data once it's fully loaded
9await shape.value
10
11// passes subscribers shape data when the shape updates
12shape.subscribe(shapeData => {
13  // shapeData is a Map of the latest value of each row in a shape.
14}

See the Docs and Examples for more information.