Overview

This SDK enables you to use the following Supabase Realtime's features:

• Broadcast: send ephemeral messages from client to clients with minimal latency. Use cases include sharing cursor positions between users.
• Presence: track and synchronize shared state across clients with the help of CRDTs. Use cases include tracking which users are currently viewing a specific webpage.
• Postgres Change Data Capture (CDC): listen for changes in your PostgreSQL database and send them to clients.

Usage

Installing the Package

npm install @supabase/realtime-js

Creating a Channel

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.')
  }
})

Notes:

• 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).
• Channel name can be any string.
• Setting private to true means that the client will use RLS to determine if the user can connect or not to a given channel.

Broadcast

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' },
    })
  }
})

Notes:

• Setting ack to true means that the channel.send promise will resolve once server replies with acknowledgment that it received the broadcast message request.
• Setting self to true means that the client will receive the broadcast message it sent out.

Broadcast Replay

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()

Presence

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)
  }
})

Postgres CDC

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!')
  }
})

Get All Channels

You can see all the channels that your client has instantiatied.

// Setup...

client.getChannels()

Cleanup

It is highly recommended that you clean up your channels after you're done with them.

• Remove a single channel

// Setup...

const channel = client.channel('some-channel-to-remove')

channel.unsubscribe()
client.removeChannel(channel)

• Remove all channels and close the connection

// Setup...

client.removeAllChannels()
client.disconnect()

Development

This package is part of the Supabase JavaScript monorepo. To work on this package:

Building

# Complete build (from monorepo root)
npx nx build realtime-js

# Build with watch mode for development
npx nx build realtime-js --watch

# Individual build targets
npx nx build:main realtime-js    # CommonJS build (dist/main/)
npx nx build:module realtime-js  # ES Modules build (dist/module/)

# Other useful commands
npx nx clean realtime-js         # Clean build artifacts
npx nx lint realtime-js          # Run ESLint
npx nx typecheck realtime-js     # TypeScript type checking

Build Outputs

• CommonJS (dist/main/) - For Node.js environments
• ES Modules (dist/module/) - For modern bundlers (Webpack, Vite, Rollup)
• TypeScript definitions (dist/module/index.d.ts) - Type definitions for TypeScript projects

Note: Unlike some other packages, realtime-js doesn't include a UMD build since it's primarily used in Node.js or bundled applications.

Validating Package Exports

# Check if package exports are correctly configured
npx 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.

Testing

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)
npx nx test realtime-js

# Run tests with coverage report
npx nx test:coverage realtime-js

# Run tests in watch mode during development
npx nx test:watch realtime-js

Test Scripts Explained

• test - Runs all unit tests once using Vitest
• test:coverage - Runs tests and generates coverage report with terminal output
• test:watch - Runs tests in interactive watch mode for development

The tests mock WebSocket connections using mock-socket, so you can run them anytime without any external dependencies.

Contributing

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.

Credits

This repo draws heavily from phoenix-js.

License

MIT.