Skip to content
Realtime

Getting Started with Realtime

Learn how to build real-time applications with Supabase Realtime

Quick start#

1. Install the client library#

npm install @supabase/supabase-js

2. Initialize the client#

Get your project URL and key.

Get API details#

To interact with data in database tables, you use the client libraries that wrap the auto-generated Data API endpoints, authenticating using the Project URL and key from the project Connect dialog.

Project URL
Publishable key
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://<project>.supabase.co', '<sb_publishable_key>')

3. Create your first Channel#

Channels are the foundation of Realtime. Think of them as rooms where clients can communicate. Each channel is identified by a topic name and if they are public or private.

// Create a channel with a descriptive topic name
const channel = supabase.channel('room:lobby:messages', {
  config: { private: true }, // Recommended for production
})

4. Set up authorization#

Since we're using a private channel, you need to create a basic RLS policy on the realtime.messages table to allow authenticated users to connect. Row Level Security (RLS) policies control who can access your Realtime channels based on user authentication and custom rules:

-- Allow authenticated users to receive broadcasts
CREATE POLICY "authenticated_users_can_receive" ON realtime.messages
  FOR SELECT TO authenticated USING (true);
-- Allow authenticated users to send broadcasts
CREATE POLICY "authenticated_users_can_send" ON realtime.messages
  FOR INSERT TO authenticated WITH CHECK (true);

5. Send and receive messages#

There are three main ways to send messages with Realtime:

5.1 using client libraries#

Send and receive messages using the Supabase client:

// Listen for messages
channel
  .on('broadcast', { event: 'message_sent' }, (payload: { payload: any }) => {
    console.log('New message:', payload.payload)
  })
  .subscribe()
// Send a message
channel.send({
  type: 'broadcast',
  event: 'message_sent',
  payload: {
    text: 'Hello, world!',
    user: 'john_doe',
    timestamp: new Date().toISOString(),
  },
})

5.2 using HTTP/REST API#

Send messages via HTTP requests, perfect for server-side applications:

// Send message via REST API
const response = await fetch(`https://<project>.supabase.co/rest/v1/rpc/broadcast`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    -H "apikey: <SECRET_KEY>"
  },
  body: JSON.stringify({
    topic: 'room:lobby:messages',
    event: 'message_sent',
    payload: {
      text: 'Hello from server!',
      user: 'system',
      timestamp: new Date().toISOString(),
    },
    private: true,
  }),
})

5.3 using database triggers#

Automatically broadcast database changes using triggers. Choose the approach that best fits your needs:

Using realtime.broadcast_changes (Best for mirroring database changes)

-- Create a trigger function for broadcasting database changes
CREATE OR REPLACE FUNCTION broadcast_message_changes()
RETURNS TRIGGER AS $$
BEGIN
  -- Broadcast to room-specific channel
  PERFORM realtime.broadcast_changes(
    'room:' || NEW.room_id::text || ':messages',
    TG_OP,
    TG_OP,
    TG_TABLE_NAME,
    TG_TABLE_SCHEMA,
    NEW,
    OLD
  );
  RETURN NULL;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;
-- Apply trigger to your messages table
CREATE TRIGGER messages_broadcast_trigger
  AFTER INSERT OR UPDATE OR DELETE ON messages
  FOR EACH ROW EXECUTE FUNCTION broadcast_message_changes();

Using realtime.send (Best for custom notifications and filtered data)

-- Create a trigger function for custom notifications
CREATE OR REPLACE FUNCTION notify_message_activity()
RETURNS TRIGGER AS $$
BEGIN
  -- Send custom notification when new message is created
  IF TG_OP = 'INSERT' THEN
    PERFORM realtime.send(
      jsonb_build_object(
        'message_id', NEW.id,
        'user_id', NEW.user_id,
        'room_id', NEW.room_id,
        'created_at', NEW.created_at
      ),
      'message_created',
      'room:' || NEW.room_id::text || ':notifications',
      true  -- private channel
    );
  END IF;
  RETURN NULL;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;
-- Apply trigger to your messages table
CREATE TRIGGER messages_notification_trigger
  AFTER INSERT ON messages
  FOR EACH ROW EXECUTE FUNCTION notify_message_activity();
  • realtime.broadcast_changes sends the full database change with metadata
  • realtime.send allows you to send custom payloads and control exactly what data is broadcast

Essential best practices#

Use private channels#

Always use private channels for production applications to ensure proper security and authorization:

const channel = supabase.channel('room:123:messages', {
  config: { private: true },
})

Follow naming conventions#

Channel Topics: Use the pattern scope:id:entity

  • room:123:messages - Messages in room 123
  • game:456:moves - Game moves for game 456
  • user:789:notifications - Notifications for user 789

Clean up subscriptions#

Always unsubscribe when you are done with a channel to ensure you free up resources:

// React example
import { useEffect } from 'react'
useEffect(() => {
  const channel = supabase.channel('room:123:messages')
  return () => {
    supabase.removeChannel(channel)
  }
}, [])

Choose the right feature#

When to use Broadcast#

  • Real-time messaging and notifications
  • Custom events and game state
  • Database change notifications (with triggers)
  • High-frequency updates (e.g. Cursor tracking)
  • Most use cases

When to use Presence#

  • User online/offline status
  • Active user counters
  • Use minimally due to computational overhead

When to use Postgres Changes#

  • Quick testing and development
  • Low amount of connected users

Next steps#

Now that you understand the basics, dive deeper into each feature:

Core features#

  • Broadcast - Learn about sending messages, database triggers, and REST API usage
  • Presence - Implement user state tracking and online indicators
  • Postgres Changes - Understanding database change listeners (consider migrating to Broadcast)

Security & configuration#

  • Authorization - Set up RLS policies for private channels
  • Settings - Configure your Realtime instance for optimal performance

Advanced topics#

  • Architecture - Understand how Realtime works under the hood
  • Benchmarks - Performance characteristics and scaling considerations
  • Limits - Usage limits and best practices

Integration guides#

Framework examples#

Ready to build something amazing? Start with the Broadcast guide to create your first real-time feature!