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. The client also supports dynamic options through function-based params and headers, making it easy to handle auth tokens, user context, and other runtime values.
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
import { ShapeStream } from '@electric-sql/client'const BASE_URL = 'http://localhost:3000'// Passes subscribers rows as they're inserted, updated, or deletedconst stream = new ShapeStream({ url: `${BASE_URL}/v1/shape`, params: { table: `foo`, },})// You can also add custom headers and URL parametersconst streamWithParams = new ShapeStream({ url: `${BASE_URL}/v1/shape`, headers: { Authorization: 'Bearer token', }, params: { table: `foo`,
Shape
import { ShapeStream, Shape } from '@electric-sql/client'const BASE_URL = 'http://localhost:3000'const stream = new ShapeStream({ url: `${BASE_URL}/v1/shape`, params: { table: `foo`, },})const shape = new Shape(stream)// Returns promise that resolves with the latest shape data once it's fully loadedawait shape.rows// passes subscribers shape data when the shape updatesshape.subscribe(({ rows }) => { // rows is an array of the latest value of each row in a shape.})
React Native / Expo app lifecycle
Metro and Expo resolve the package's react-native export for native builds, so standard imports automatically wire React Native AppState into ShapeStream. If your bundler setup does not resolve the root react-native condition, use the explicit @electric-sql/client/react-native entrypoint or pass runtimeVisibility explicitly. See the TypeScript client docs for details.
Error Handling
The ShapeStream provides robust error handling with automatic retry support:
1. Stream-level error handler with retry control
The onError handler gives you full control over error recovery:
import { ShapeStream, FetchError } from '@electric-sql/client'const BASE_URL = 'http://localhost:3000'const getRefreshedToken = () => 'refreshed-token'const fallbackUserId = 'fallback-user-id'const stream = new ShapeStream({ url: `${BASE_URL}/v1/shape`, params: { table: `foo` }, onError: (error) => { console.error('Stream error:', error) // IMPORTANT: Return an object to keep syncing! // Return void/undefined to stop syncing permanently. // Note: 5xx errors and network errors are automatically retried, // so onError is mainly for handling client errors (4xx)
Critical: The onError callback's return value controls whether syncing continues:
Return an object (even empty {}) to retry syncing:
{} - Retry with same params and headers
{ params } - Retry with modified params
{ headers } - Retry with modified headers
{ params, headers } - Retry with both modified
Return void/undefined to stop the stream permanently
Automatic retries: The client automatically retries 5xx server errors, network errors, and 429 rate limits with exponential backoff. The onError callback is only invoked after these retries are exhausted, or for non-retryable errors like 4xx client errors.
Without onError: If no onError handler is provided, non-retryable errors (like 4xx client errors) will be thrown and the stream will stop.
2. Subscription-level error callbacks
Individual subscribers can handle errors specific to their subscription:
stream.subscribe( (messages) => { // Handle messages }, (error) => { // Handle errors for this specific subscription console.error('Subscription error:', error) })
Note: Subscription error callbacks cannot control retry behavior - use the stream-level onError for that.