Realtime Quickstart

Learn how to build multiplayer.dev, a collaborative app that demonstrates Broadcast, Presence, and Postgres CDC using Realtime.

Install supabase-js Client#

npm install @supabase/supabase-js

Cursor Positions#

Broadcast allows a client to send messages and multiple clients to receive the messages. The broadcasted messages are ephemeral. They are not persisted to the database and are directly relayed through the Realtime servers. This is ideal for sending information like cursor positions where minimal latency is important, but persisting them is not.

In multiplayer.dev, client's cursor positions are sent to other clients in the room. However, cursor positions will be randomly generated for this example.

You need to get the public anon access token from your project's API settings. Then you can set up the Supabase client and start sending a client's cursor positions to other clients in channel room1:

1const { createClient } = require('@supabase/supabase-js')
2
3const supabase = createClient('https://your-project-ref.supabase.co', 'anon-key', {
4  realtime: {
5    params: {
6      eventsPerSecond: 10,
7    },
8  },
9})
10
11// Channel name can be any string.
12// Create channels with the same name for both the broadcasting and receiving clients.
13const channel = supabase.channel('room1')
14
15// Subscribe registers your client with the server
16channel.subscribe((status) => {
17  if (status === 'SUBSCRIBED') {
18    // now you can start broadcasting cursor positions
19    setInterval(() => {
20      channel.send({
21        type: 'broadcast',
22        event: 'cursor-pos',
23        payload: { x: Math.random(), y: Math.random() },
24      })
25      console.log(status)
26    }, 100)
27  }
28})

Another client can subscribe to channel room1 and receive cursor positions:

1// Supabase client setup
2
3// Listen to broadcast messages.
4supabase
5  .channel('room1')
6  .on('broadcast', { event: 'cursor-pos' }, (payload) => console.log(payload))
7  .subscribe((status) => {
8    if (status === 'SUBSCRIBED') {
9      // your callback function will now be called with the messages broadcast by the other client
10    }
11  })

Roundtrip Latency#

You can also configure the channel so that the server must return an acknowledgement that it received the broadcast message. This is useful if you want to measure the roundtrip latency:

1// Supabase client setup
2
3const channel = supabase.channel('calc-latency', {
4  config: {
5    broadcast: { ack: true },
6  },
7})
8
9channel.subscribe(async (status) => {
10  if (status === 'SUBSCRIBED') {
11    const begin = performance.now()
12
13    await channel.send({
14      type: 'broadcast',
15      event: 'latency',
16      payload: {},
17    })
18
19    const end = performance.now()
20
21    console.log(`Latency is ${end - begin} milliseconds`)
22  }
23})

Track and display which users are online#

Presence stores and synchronize shared state across clients. The sync event is triggered whenever the shared state changes. The join event is triggered when new clients join the channel and leave event is triggered when clients leave.

Each client can use the channel's track method to store an object in shared state. Each client can only track one object, and if track is called again by the same client, then the new object overwrites the previously tracked object in the shared state. You can use one client to track and display users who are online:

1// Supabase client setup
2
3const channel = supabase.channel('online-users', {
4  config: {
5    presence: {
6      key: 'user1',
7    },
8  },
9})
10
11channel.on('presence', { event: 'sync' }, () => {
12  console.log('Online users: ', channel.presenceState())
13})
14
15channel.on('presence', { event: 'join' }, ({ newPresences }) => {
16  console.log('New users have joined: ', newPresences)
17})
18
19channel.on('presence', { event: 'leave' }, ({ leftPresences }) => {
20  console.log('Users have left: ', newPresences)
21})
22
23channel.subscribe(async (status) => {
24  if (status === 'SUBSCRIBED') {
25    const status = await channel.track({ online_at: new Date().toISOString() })
26    console.log(status)
27  }
28})

Then you can use another client to add another user to the channel's Presence state:

1// Supabase client setup
2
3const channel = supabase.channel('online-users', {
4  config: {
5    presence: {
6      key: 'user2',
7    },
8  },
9})
10
11// Presence event handlers setup
12
13channel.subscribe(async (status) => {
14  if (status === 'SUBSCRIBED') {
15    const status = await channel.track({ online_at: new Date().toISOString() })
16    console.log(status)
17  }
18})

If a channel is set up without a presence key, the server generates a random UUID. type must be presence and event must be either sync, join, or leave.

Insert and Receive Persisted Messages#

Postgres Change Data Capture (CDC) enables your client to insert, update, or delete database records and send the changes to clients. Create a messages table to keep track of messages created by users in specific rooms:

1create table messages (
2  id serial primary key,
3  message text,
4  user_id text,
5  room_id text,
6  created_at timestamptz default now()
7)
8
9alter table messages enable row level security;
10
11create policy "anon_ins_policy"
12ON messages
13for insert
14to anon
15with check (true);
16
17create policy "anon_sel_policy"
18ON messages
19for select
20to anon
21using (true);

If it doesn't already exist, create a supabase_realtime publication and add messages table to the publication:

1begin;
2  -- remove the supabase_realtime publication
3  drop publication if exists supabase_realtime;
4
5  -- re-create the supabase_realtime publication with no tables and only for insert
6  create publication supabase_realtime with (publish = 'insert');
7commit;
8
9-- add a table to the publication
10alter publication supabase_realtime add table messages;

You can then have a client listen for changes on the messages table for a specific room and send and receive persisted messages:

1// Supabase client setup
2
3const channel = supabase.channel('db-messages')
4
5const roomId = 'room1'
6const userId = 'user1'
7
8channel.on(
9  'postgres_changes',
10  {
11    event: 'INSERT',
12    schema: 'public',
13    table: 'messages',
14    filter: `room_id=eq.${roomId}`,
15  },
16  (payload) => console.log(payload)
17)
18
19channel.subscribe(async (status) => {
20  if (status === 'SUBSCRIBED') {
21    const res = await supabase.from('messages').insert({
22      room_id: roomId,
23      user_id: userId,
24      message: 'Welcome to Realtime!',
25    })
26    console.log(res)
27  }
28})