@supabase/realtime-js

What is @supabase/realtime-js?

@supabase/realtime-js is a JavaScript client for interacting with Supabase's real-time features. It allows developers to subscribe to changes in their database and receive updates in real-time, enabling functionalities such as live data synchronization, real-time notifications, and collaborative applications.

What are @supabase/realtime-js's main functionalities?

Real-time Database Changes

This feature allows you to subscribe to changes in a specific table in your Supabase database. The code sample demonstrates how to set up a subscription to listen for any changes (insert, update, delete) on the 'your_table' table and log the payload of the change.

const { createClient } = require('@supabase/supabase-js');
const supabase = createClient('https://your-project.supabase.co', 'public-anon-key');

const subscription = supabase
  .from('your_table')
  .on('*', payload => {
    console.log('Change received!', payload);
  })
  .subscribe();

Real-time Insertions

This feature allows you to subscribe specifically to insertions in a table. The code sample shows how to listen for new rows being added to 'your_table' and log the payload of the new row.

const { createClient } = require('@supabase/supabase-js');
const supabase = createClient('https://your-project.supabase.co', 'public-anon-key');

const subscription = supabase
  .from('your_table')
  .on('INSERT', payload => {
    console.log('New row added!', payload);
  })
  .subscribe();

Real-time Updates

This feature allows you to subscribe specifically to updates in a table. The code sample demonstrates how to listen for updates to rows in 'your_table' and log the payload of the updated row.

const { createClient } = require('@supabase/supabase-js');
const supabase = createClient('https://your-project.supabase.co', 'public-anon-key');

const subscription = supabase
  .from('your_table')
  .on('UPDATE', payload => {
    console.log('Row updated!', payload);
  })
  .subscribe();

Real-time Deletions

This feature allows you to subscribe specifically to deletions in a table. The code sample shows how to listen for rows being deleted from 'your_table' and log the payload of the deleted row.

const { createClient } = require('@supabase/supabase-js');
const supabase = createClient('https://your-project.supabase.co', 'public-anon-key');

const subscription = supabase
  .from('your_table')
  .on('DELETE', payload => {
    console.log('Row deleted!', payload);
  })
  .subscribe();

Other packages similar to @supabase/realtime-js

socket.io

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-js

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

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.

README

Supabase Realtime Client

Send ephemeral messages with Broadcast, track and synchronize state with Presence, and listen to database changes with Postgres Change Data Capture (CDC).

Guides · Reference Docs · Multiplayer Demo

Overview

This client 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,
    eventsPerSecond: 10,
  },
})

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.
• eventsPerSecond, or client-side rate limiting, enforces the number of events sent to the Realtime server uniformly spread across a second. The default is 10, which means that the client can send one event, whether that's Broadcast/Presence/Postgres CDC, every 100 milliseconds. You may change this as you see fit but note that the server's rate limiting will need to be updated accordingly. You can learn more about Realtime's rate limits here: https://supabase.com/docs/guides/realtime/rate-limits.

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 acknowledgement that it received the broadcast message request.
• Setting self to true means that the client will receive the broadcast message it sent out.

Presence

Your client can track and sync state that's stored in the channel.

// Setup...

const channel = client.channel('presence-test', { 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: ', newPresences)
})

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

client.removeChannel(channel)

• Remove all channels

// Setup...

const channel1 = client.channel('a-channel-to-remove')
const channel2 = client.channel('another-channel-to-remove')

channel1.subscribe()
channel2.subscribe()

client.removeAllChannels()

Credits

This repo draws heavily from phoenix-js.

License

MIT.