Supabase Realtime

You are a Supabase backend developer. The user wants to build real-time features using Supabase's subscription system to listen for database changes and broadcast events.

What to check first

• Run npm list @supabase/supabase-js to confirm the client library is installed (v2.0+)
• Verify that Realtime is enabled in your Supabase project settings under "Replication" for your target tables
• Check that your Supabase project URL and anon key are available in your environment variables

Steps

1. Import the Supabase client and create an instance with your project URL and anon key
2. Set up a postgres_changes subscription using .on() to listen for INSERT, UPDATE, or DELETE events on a specific table
3. Use the .subscribe() method to activate the listener and establish the WebSocket connection
4. Handle the payload object which contains eventType, old, and new data for each change
5. Implement error handling by passing a callback to .on('postgres_changes') or the .subscribe() promise
6. Unsubscribe from the channel using .unsubscribe() when the component unmounts or the listener is no longer needed
7. For broadcast messages (non-database events), use .on('broadcast', ...) instead of postgres_changes
8. Test the real-time connection by making database changes in another client and verifying the subscription receives updates

Code

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);

// Listen for real-time database changes on the 'messages' table
const channel = supabase
  .channel('public:messages')
  .on(
    'postgres_changes',
    {
      event: '*', // Listen for all events: INSERT, UPDATE, DELETE
      schema: 'public',
      table: 'messages'
    },
    (payload) => {
      console.log('Change received!', payload);
      const { eventType, new: newRecord, old: oldRecord } = payload;
      
      if (eventType === 'INSERT') {
        console.log('New message:', newRecord);
      } else if (eventType === 'UPDATE') {
        console.log('Updated from:', oldRecord, 'to:', newRecord);
      } else if (eventType === 'DELETE') {
        console.log('Deleted message:', oldRecord);
      }
    }
  )
  .on(
    'broadcast',
    { event: 'user_typing' },
    (payload) => {
      console.log('User typing event:', payload.payload);
    }
  )
  .subscribe((status) => {
    if (status === 'SUBSCRIBED') {
      console.log('Real-time subscription active');
    }

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change