# Understanding and Monitoring Realtime Heartbeats

## What are heartbeat messages?

Heartbeat messages are periodic signals sent between the Realtime client and server to verify that the WebSocket connection is alive and functioning properly. The client sends a heartbeat message on the `phoenix` topic with the event type `heartbeat` at regular intervals (default: 25 seconds), and the server responds with a `phx_reply` message.

These messages serve as a keep-alive mechanism to detect connection issues that might not be immediately apparent, such as silent network failures or intermediary proxy timeouts.

## Why heartbeats matter

Heartbeat messages are critical for maintaining reliable real-time connections:

- **Connection health monitoring**: They detect when a connection has silently failed without triggering WebSocket close events
- **Automatic recovery**: When heartbeats time out, the client automatically attempts to reconnect
- **Network proxy compatibility**: Many network proxies and load balancers close idle connections; heartbeats keep the connection active
- **Early issue detection**: Heartbeat timeouts alert you to connection problems before users experience message delivery failures

Without heartbeats, your application might appear connected while being unable to send or receive messages.

## How to handle heartbeat messages

You can monitor heartbeat lifecycle events using the `onHeartbeat` method:

```tsx
import { createClient } from '@supabase/supabase-js'
import { useEffect } from 'react'

function MyComponent() {
  const supabase = createClient(SUPABASE_URL, SUPABASE_KEY)

  useEffect(() => {
    supabase.realtime.onHeartbeat((status) => {
      console.log('Heartbeat status:', status)
      // status can be: 'sent', 'ok', 'error', 'timeout', or 'disconnected'
    })
  }, [supabase])

  return <div>Your app content</div>
}
```

Or configure the callback during client initialization:

```tsx
const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
  realtime: {
    heartbeatCallback: (status) => {
      console.log('Heartbeat status:', status)
    },
  },
})
```

## Troubleshooting heartbeat issues

### Frequent heartbeat timeouts

If you're seeing frequent `timeout` status in your heartbeat callback:

- **Network instability**: Check your network connection quality
- **Firewall/proxy issues**: Corporate firewalls or proxies might interfere with WebSocket connections
- **Mobile app suspension**: On mobile, the app can be suspended which can stop the heartbeat timers

**Connection not reconnecting after timeout**

The client automatically attempts reconnection with exponential backoff (1s, 2s, 5s, 10s). If you need to manually reconnect:

```tsx
import { createClient } from '@supabase/supabase-js'
import { useEffect, useState } from 'react'

function ConnectionStatus() {
  const supabase = createClient(SUPABASE_URL, SUPABASE_KEY)
  const [isConnected, setIsConnected] = useState(true)

  useEffect(() => {
    supabase.realtime.onHeartbeat((status) => {
      if (status === 'ok') {
        setIsConnected(true)
      } else if (status === 'timeout' || status === 'disconnected') {
        setIsConnected(false)
      }
    })
  }, [supabase])

  const handleReconnect = () => {
    supabase.realtime.connect()
  }

  return (
    <div>
      <p>Status: {isConnected ? 'Connected' : 'Disconnected'}</p>
      {!isConnected && <button onClick={handleReconnect}>Reconnect</button>}
    </div>
  )
}
```

### Customizing heartbeat interval

You can adjust the heartbeat frequency when creating your Supabase client in React:

```tsx
import { createClient } from '@supabase/supabase-js'
import { useMemo } from 'react'

function App() {
  const supabase = useMemo(
    () =>
      createClient(SUPABASE_URL, SUPABASE_KEY, {
        realtime: {
          heartbeatIntervalMs: 15000, // Send heartbeat every 15 seconds (default: 25000)
        },
      }),
    []
  )

  return <YourApp supabase={supabase} />
}
```

Note: Increasing the interval reduces network traffic but delays detection of connection failures. Decreasing it improves detection speed but increases overhead.

### Heartbeat errors in Web workers

For React applications with long-running connections, use Web Workers to prevent browser tab throttling:

```tsx
import { createClient } from '@supabase/supabase-js'
import { useMemo } from 'react'

function App() {
  const supabase = useMemo(
    () =>
      createClient(SUPABASE_URL, SUPABASE_KEY, {
        realtime: {
          worker: true,
          workerUrl: '/worker.js', // Optional: Place in public folder
        },
      }),
    []
  )

  return <YourApp supabase={supabase} />
}
```

If the worker fails to start, check:

- Browser Web Worker support is available
- Worker script is in the public folder and accessible
- CORS headers allow loading the worker script

## Best practices

### Show connection status to users

Display connection status with an indicator:

```tsx
import { createClient } from '@supabase/supabase-js'
import { useEffect, useState } from 'react'

function ConnectionIndicator() {
  const supabase = createClient(SUPABASE_URL, SUPABASE_KEY)
  const [status, setStatus] = useState('healthy')

  useEffect(() => {
    supabase.realtime.onHeartbeat((heartbeatStatus) => {
      if (heartbeatStatus === 'ok') {
        setStatus('healthy')
      } else if (heartbeatStatus === 'timeout') {
        setStatus('poor')
      } else if (heartbeatStatus === 'disconnected') {
        setStatus('disconnected')
      }
    })
  }, [supabase])

  return (
    <div>
      <span>Connection: {status}</span>
    </div>
  )
}
```

### Reconnect when React Native app comes to foreground

Ensure connection is active when user opens your app:

```tsx
import { createClient } from '@supabase/supabase-js'
import { useEffect } from 'react'
import { AppState } from 'react-native'

function App() {
  const supabase = createClient(SUPABASE_URL, SUPABASE_KEY)

  useEffect(() => {
    const subscription = AppState.addEventListener('change', (nextAppState) => {
      if (nextAppState === 'active') {
        if (!supabase.realtime.isConnected()) {
          supabase.realtime.connect()
        }
      }
    })

    return () => {
      subscription.remove()
    }
  }, [supabase])

  return <YourApp />
}
```

### Monitor connection in your entire app

Set up monitoring when you create your Supabase client:

```tsx
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
  realtime: {
    heartbeatCallback: (status) => {
      if (status === 'ok') {
        console.log('Connection healthy')
      } else if (status === 'timeout') {
        console.warn('Connection slow')
      } else if (status === 'disconnected') {
        console.error('Disconnected')
      }
    },
  },
})

export default supabase
```