@supabase/realtime-js
Advanced tools
Guides · Reference Docs · Multiplayer Demo
This SDK enables you to use the following Supabase Realtime's features:
npm install @supabase/realtime-js
import { RealtimeClient } from '@supabase/realtime-js'
const client = new RealtimeClient(REALTIME_URL, {
params: {
apikey: API_KEY,
},
})
const channel = client.channel('test-channel', {})
channel.subscribe((status, err) => {
if (status === 'SUBSCRIBED') {
console.log('Connected!')
}
if (status === 'CHANNEL_ERROR') {
console.log(`There was an error subscribing to channel: ${err.message}`)
}
if (status === 'TIMED_OUT') {
console.log('Realtime server did not respond in time.')
}
if (status === 'CLOSED') {
console.log('Realtime channel was unexpectedly closed.')
}
})
REALTIME_URL is 'ws://localhost:4000/socket' when developing locally and 'wss://<project_ref>.supabase.co/realtime/v1' when connecting to your Supabase project.API_KEY is a JWT whose claims must contain exp and role (existing database role).string.private to true means that the client will use RLS to determine if the user can connect or not to a given channel.Your client can send and receive messages based on the event.
// Setup...
const channel = client.channel('broadcast-test', { broadcast: { ack: false, self: false } })
channel.on('broadcast', { event: 'some-event' }, (payload) => console.log(payload))
channel.subscribe(async (status) => {
if (status === 'SUBSCRIBED') {
// Send message to other clients listening to 'broadcast-test' channel
await channel.send({
type: 'broadcast',
event: 'some-event',
payload: { hello: 'world' },
})
}
})
ack to true means that the channel.send promise will resolve once server replies with acknowledgment that it received the broadcast message request.self to true means that the client will receive the broadcast message it sent out.Broadcast Replay enables private channels to access messages that were sent earlier. Only messages published via Broadcast From the Database are available for replay.
You can configure replay with the following options:
since (Required): The epoch timestamp in milliseconds, specifying the earliest point from which messages should be retrieved.limit (Optional): The number of messages to return. This must be a positive integer, with a maximum value of 25.Example:
const twelveHours = 12 * 60 * 60 * 1000
const twelveHoursAgo = Date.now() - twelveHours
const config = { private: true, broadcast: { replay: { since: twelveHoursAgo, limit: 10 } } }
supabase
.channel('main:room', { config })
.on('broadcast', { event: 'my_event' }, (payload) => {
if (payload?.meta?.replayed) {
console.log('This message was sent earlier:', payload)
} else {
console.log('This is a new message', payload)
}
// ...
})
.subscribe()
Your client can track and sync state that's stored in the channel.
// Setup...
const channel = client.channel('presence-test', {
config: {
presence: {
key: '',
},
},
})
channel.on('presence', { event: 'sync' }, () => {
console.log('Online users: ', channel.presenceState())
})
channel.on('presence', { event: 'join' }, ({ newPresences }) => {
console.log('New users have joined: ', newPresences)
})
channel.on('presence', { event: 'leave' }, ({ leftPresences }) => {
console.log('Users have left: ', leftPresences)
})
channel.subscribe(async (status) => {
if (status === 'SUBSCRIBED') {
const status = await channel.track({ user_id: 1 })
console.log(status)
}
})
config.presence.enabled(set automatically if you add an.on('presence', ...)listener) controls whether this client receives presence state and updates from other clients — without it,presenceState()stays empty for you. It does not affect whether other clients see you: callingtrack()always makes you visible to subscribers that do have presence enabled. On RLS-protected channels, receiving presence updates additionally requires thepresence.readpolicy to authorize this client.
Receive database changes on the client.
// Setup...
const channel = client.channel('db-changes')
channel.on('postgres_changes', { event: '*', schema: 'public' }, (payload) => {
console.log('All changes in public schema: ', payload)
})
channel.on(
'postgres_changes',
{ event: 'INSERT', schema: 'public', table: 'messages' },
(payload) => {
console.log('All inserts in messages table: ', payload)
}
)
channel.on(
'postgres_changes',
{ event: 'UPDATE', schema: 'public', table: 'users', filter: 'username=eq.Realtime' },
(payload) => {
console.log('All updates on users table when username is Realtime: ', payload)
}
)
channel.subscribe(async (status) => {
if (status === 'SUBSCRIBED') {
console.log('Ready to receive database changes!')
}
})
The filter option accepts either a raw string or a
postgresChangesFilter() builder — both produce the exact same wire format, so
you can mix and match and existing string filters keep working unchanged:
// Raw string — always supported, fully backward compatible
{ event: 'UPDATE', schema: 'public', table: 'users', filter: 'id=eq.1' }
// Builder — type-checked, ergonomic; the SDK serializes it for you
{ event: 'UPDATE', schema: 'public', table: 'users', filter: postgresChangesFilter().eq('id', 1) }
A filter is a column=operator.value expression evaluated server-side. The
following operators are supported:
| Operator | String form | Builder | Meaning |
|---|---|---|---|
eq | id=eq.1 | .eq('id', 1) | equal |
neq | id=neq.1 | .neq('id', 1) | not equal |
lt lte gt gte | age=gte.18 | .gte('age', 18) | comparison |
in | status=in.(active,pending) | .in('status', ['active', 'pending']) | in list |
like ilike | title=like.%foo% | .like('title', '%foo%') | pattern match (case in/sensitive) |
is | deleted_at=is.null | .is('deleted_at', null) | IS null/true/false/unknown |
match imatch | title=match.^foo | .match('title', '^foo') | POSIX regex match (~ / ~*) |
isdistinct | value=isdistinct.1 | .isDistinct('value', 1) | NULL-safe inequality |
Negation — prefix any operator with not. (string) or use
.not(column, operator, value) (builder):
// String
{ event: '*', schema: 'public', table: 'posts', filter: 'status=not.in.(draft,archived)' }
// Builder
{
event: '*',
schema: 'public',
table: 'posts',
filter: postgresChangesFilter().not('status', 'in', ['draft', 'archived']),
}
AND composition — multiple conditions are combined with commas and applied
as an AND. With the builder you just chain calls:
// String
{ event: 'UPDATE', schema: 'public', table: 'orders', filter: 'amount=gt.100,status=in.(open,pending)' }
// Builder — equivalent, chained
{
event: 'UPDATE',
schema: 'public',
table: 'orders',
filter: postgresChangesFilter().gt('amount', 100).in('status', ['open', 'pending']),
}
postgresChangesFilter()The builder (modeled on the postgrest-js filter methods) is the recommended,
type-checked way to compose filters — but it is entirely optional; raw strings
remain fully supported.
import { postgresChangesFilter } from '@supabase/realtime-js'
channel.on(
'postgres_changes',
{
event: 'UPDATE',
schema: 'public',
table: 'orders',
// → 'amount=gt.100,status=not.in.(draft,archived)'
filter: postgresChangesFilter().gt('amount', 100).not('status', 'in', ['draft', 'archived']),
},
(payload) => console.log(payload)
)
The builder exposes eq, neq, gt, gte, lt, lte, in, like,
ilike, match, imatch, is, isDistinct and not. Call .build() if you
need the raw string yourself (e.g. to log it or store it).
Values are sent verbatim — the server has no quoting/escaping, so spaces and
quotes are preserved as-is. The server separates conditions by commas outside
parentheses, so a literal comma in a scalar value can't be expressed (commas
inside in.(…) are fine); the builder throws on such values rather than
silently producing a broken filter.
Note for PostgREST users: Realtime evaluates filters server-side over a single table's WAL — there is no resource embedding (
!inner, embedded filters) and noor()grouping. Use%(not*) forlike/ilikewildcards, since filters travel in the WebSocket payload rather than a URL.
Use select to receive only a subset of columns instead of the full row. This
reduces payload size (helpful for large bytea/jsonb columns). The selected
columns must be selectable by the subscribing role:
channel.on(
'postgres_changes',
{ event: '*', schema: 'public', table: 'users', select: ['id', 'first_name'] },
(payload) => {
// payload.new only contains { id, first_name }
console.log(payload)
}
)
You can see all the channels that your client has instantiatied.
// Setup...
client.getChannels()
It is highly recommended that you clean up your channels after you're done with them.
// Setup...
const channel = client.channel('some-channel-to-remove')
channel.unsubscribe()
client.removeChannel(channel)
// Setup...
client.removeAllChannels()
client.disconnect()
This package is part of the Supabase JavaScript monorepo. To work on this package:
# Complete build (from monorepo root)
pnpm nx build realtime-js
# Build with watch mode for development
pnpm nx build realtime-js --watch
# Individual build targets
pnpm nx build:main realtime-js # CommonJS build (dist/main/)
pnpm nx build:module realtime-js # ES Modules build (dist/module/)
# Other useful commands
pnpm nx clean realtime-js # Clean build artifacts
pnpm nx lint realtime-js # Run ESLint
pnpm nx typecheck realtime-js # TypeScript type checking
dist/main/) - For Node.js environmentsdist/module/) - For modern bundlers (Webpack, Vite, Rollup)dist/module/index.d.ts) - Type definitions for TypeScript projectsNote: Unlike some other packages, realtime-js doesn't include a UMD build since it's primarily used in Node.js or bundled applications.
# Check if package exports are correctly configured
pnpm nx check-exports realtime-js
This command uses "Are the types wrong?" to verify that the package exports work correctly in different environments. Run this before publishing to ensure your package can be imported correctly by all consumers.
No Docker or Supabase instance required! The realtime-js tests use mocked WebSocket connections, so they're completely self-contained.
# Run unit tests (from monorepo root)
pnpm nx test realtime-js
# Run tests with coverage report
pnpm nx test:coverage realtime-js
# Run tests in watch mode during development
pnpm nx test:watch realtime-js
The tests mock WebSocket connections using mock-socket, so you can run them anytime without any external dependencies.
We welcome contributions! Please see our Contributing Guide for details on how to get started.
For major changes or if you're unsure about something, please open an issue first to discuss your proposed changes.
This repo draws heavily from phoenix-js.
MIT.
Socket.IO is a library that enables real-time, bidirectional and event-based communication between web clients and servers. Unlike @supabase/realtime-js, which is tightly integrated with Supabase's database, Socket.IO is more general-purpose and can be used for a wide range of real-time applications, including chat applications, live updates, and collaborative tools.
Pusher is a hosted service that makes it easy to add real-time data and functionality to web and mobile applications. Pusher channels provide a way to subscribe to events and receive updates in real-time. Compared to @supabase/realtime-js, Pusher is a more mature and feature-rich platform but requires a separate service subscription.
Firebase is a comprehensive app development platform that includes real-time database capabilities. Firebase Realtime Database allows you to store and sync data between your users in real-time. While @supabase/realtime-js focuses on real-time features for Supabase's PostgreSQL database, Firebase offers a NoSQL database with built-in real-time synchronization.
FAQs
Listen to realtime updates to your PostgreSQL database
The npm package @supabase/realtime-js receives a total of 17,177,281 weekly downloads. As such, @supabase/realtime-js popularity was classified as popular.
We found that @supabase/realtime-js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A new federal program will let vetted U.S. cybersecurity firms help investigate and disrupt foreign cybercrime groups under government direction.
Research
/Security News
The campaign amassed more than 75,000 installs by targeting Russian-speaking users seeking access to blocked services.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.