Send ephemeral messages with Broadcast, track and synchronize state with Presence, and listen to database changes with Postgres Change Data Capture (CDC).
\n\n# Overview\n\nThis SDK enables you to use the following Supabase Realtime's features:\n\n- **Broadcast**: send ephemeral messages from client to clients with minimal latency. Use cases include sharing cursor positions between users.\n- **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.\n- **Postgres Change Data Capture (CDC)**: listen for changes in your PostgreSQL database and send them to clients.\n\n# Usage\n\n## Installing the Package\n\n```bash\nnpm install @supabase/realtime-js\n```\n\n## Creating a Channel\n\n```js\nimport { RealtimeClient } from '@supabase/realtime-js'\n\nconst client = new RealtimeClient(REALTIME_URL, {\n params: {\n apikey: API_KEY,\n },\n})\n\nconst channel = client.channel('test-channel', {})\n\nchannel.subscribe((status, err) => {\n if (status === 'SUBSCRIBED') {\n console.log('Connected!')\n }\n\n if (status === 'CHANNEL_ERROR') {\n console.log(`There was an error subscribing to channel: ${err.message}`)\n }\n\n if (status === 'TIMED_OUT') {\n console.log('Realtime server did not respond in time.')\n }\n\n if (status === 'CLOSED') {\n console.log('Realtime channel was unexpectedly closed.')\n }\n})\n```\n\n### Notes:\n\n- `REALTIME_URL` is `'ws://localhost:4000/socket'` when developing locally and `'wss://.supabase.co/realtime/v1'` when connecting to your Supabase project.\n- `API_KEY` is a JWT whose claims must contain `exp` and `role` (existing database role).\n- Channel name can be any `string`.\n- Setting `private` to `true` means that the client will use RLS to determine if the user can connect or not to a given channel.\n\n## Broadcast\n\nYour client can send and receive messages based on the `event`.\n\n```js\n// Setup...\n\nconst channel = client.channel('broadcast-test', { broadcast: { ack: false, self: false } })\n\nchannel.on('broadcast', { event: 'some-event' }, (payload) => console.log(payload))\n\nchannel.subscribe(async (status) => {\n if (status === 'SUBSCRIBED') {\n // Send message to other clients listening to 'broadcast-test' channel\n await channel.send({\n type: 'broadcast',\n event: 'some-event',\n payload: { hello: 'world' },\n })\n }\n})\n```\n\n### Notes:\n\n- Setting `ack` to `true` means that the `channel.send` promise will resolve once server replies with acknowledgment that it received the broadcast message request.\n- Setting `self` to `true` means that the client will receive the broadcast message it sent out.\n\n### Broadcast Replay\n\nBroadcast Replay enables **private** channels to access messages that were sent earlier. Only messages published via [Broadcast From the Database](https://supabase.com/docs/guides/realtime/broadcast#trigger-broadcast-messages-from-your-database) are available for replay.\n\nYou can configure replay with the following options:\n\n- **`since`** (Required): The epoch timestamp in milliseconds, specifying the earliest point from which messages should be retrieved.\n- **`limit`** (Optional): The number of messages to return. This must be a positive integer, with a maximum value of 25.\n\nExample:\n\n```typescript\nconst twelveHours = 12 * 60 * 60 * 1000\nconst twelveHoursAgo = Date.now() - twelveHours\n\nconst config = { private: true, broadcast: { replay: { since: twelveHoursAgo, limit: 10 } } }\n\nsupabase\n .channel('main:room', { config })\n .on('broadcast', { event: 'my_event' }, (payload) => {\n if (payload?.meta?.replayed) {\n console.log('This message was sent earlier:', payload)\n } else {\n console.log('This is a new message', payload)\n }\n // ...\n })\n .subscribe()\n```\n\n## Presence\n\nYour client can track and sync state that's stored in the channel.\n\n```js\n// Setup...\n\nconst channel = client.channel('presence-test', {\n config: {\n presence: {\n key: '',\n },\n },\n})\n\nchannel.on('presence', { event: 'sync' }, () => {\n console.log('Online users: ', channel.presenceState())\n})\n\nchannel.on('presence', { event: 'join' }, ({ newPresences }) => {\n console.log('New users have joined: ', newPresences)\n})\n\nchannel.on('presence', { event: 'leave' }, ({ leftPresences }) => {\n console.log('Users have left: ', leftPresences)\n})\n\nchannel.subscribe(async (status) => {\n if (status === 'SUBSCRIBED') {\n const status = await channel.track({ user_id: 1 })\n console.log(status)\n }\n})\n```\n\n## Postgres CDC\n\nReceive database changes on the client.\n\n```js\n// Setup...\n\nconst channel = client.channel('db-changes')\n\nchannel.on('postgres_changes', { event: '*', schema: 'public' }, (payload) => {\n console.log('All changes in public schema: ', payload)\n})\n\nchannel.on(\n 'postgres_changes',\n { event: 'INSERT', schema: 'public', table: 'messages' },\n (payload) => {\n console.log('All inserts in messages table: ', payload)\n }\n)\n\nchannel.on(\n 'postgres_changes',\n { event: 'UPDATE', schema: 'public', table: 'users', filter: 'username=eq.Realtime' },\n (payload) => {\n console.log('All updates on users table when username is Realtime: ', payload)\n }\n)\n\nchannel.subscribe(async (status) => {\n if (status === 'SUBSCRIBED') {\n console.log('Ready to receive database changes!')\n }\n})\n```\n\n## Get All Channels\n\nYou can see all the channels that your client has instantiatied.\n\n```js\n// Setup...\n\nclient.getChannels()\n```\n\n## Cleanup\n\nIt is highly recommended that you clean up your channels after you're done with them.\n\n- Remove a single channel\n\n```js\n// Setup...\n\nconst channel = client.channel('some-channel-to-remove')\n\nchannel.unsubscribe()\nclient.removeChannel(channel)\n```\n\n- Remove all channels and close the connection\n\n```js\n// Setup...\n\nclient.removeAllChannels()\nclient.disconnect()\n```\n\n## Development\n\nThis package is part of the [Supabase JavaScript monorepo](https://github.com/supabase/supabase-js). To work on this package:\n\n### Building\n\n```bash\n# Complete build (from monorepo root)\nnpx nx build realtime-js\n\n# Build with watch mode for development\nnpx nx build realtime-js --watch\n\n# Individual build targets\nnpx nx build:main realtime-js # CommonJS build (dist/main/)\nnpx nx build:module realtime-js # ES Modules build (dist/module/)\n\n# Other useful commands\nnpx nx clean realtime-js # Clean build artifacts\nnpx nx lint realtime-js # Run ESLint\nnpx nx typecheck realtime-js # TypeScript type checking\n```\n\n#### Build Outputs\n\n- **CommonJS (`dist/main/`)** - For Node.js environments\n- **ES Modules (`dist/module/`)** - For modern bundlers (Webpack, Vite, Rollup)\n- **TypeScript definitions (`dist/module/index.d.ts`)** - Type definitions for TypeScript projects\n\nNote: Unlike some other packages, realtime-js doesn't include a UMD build since it's primarily used in Node.js or bundled applications.\n\n#### Validating Package Exports\n\n```bash\n# Check if package exports are correctly configured\nnpx nx check-exports realtime-js\n```\n\nThis command uses [\"Are the types wrong?\"](https://github.com/arethetypeswrong/arethetypeswrong.github.io) to verify that the package exports work correctly in different environments. Run this before publishing to ensure your package can be imported correctly by all consumers.\n\n### Testing\n\n**No Docker or Supabase instance required!** The realtime-js tests use mocked WebSocket connections, so they're completely self-contained.\n\n```bash\n# Run unit tests (from monorepo root)\nnpx nx test realtime-js\n\n# Run tests with coverage report\nnpx nx test:coverage realtime-js\n\n# Run tests in watch mode during development\nnpx nx test:watch realtime-js\n```\n\n#### Test Scripts Explained\n\n- **test** - Runs all unit tests once using Vitest\n- **test:coverage** - Runs tests and generates coverage report with terminal output\n- **test:watch** - Runs tests in interactive watch mode for development\n\nThe tests mock WebSocket connections using `mock-socket`, so you can run them anytime without any external dependencies.\n\n### Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](../../../CONTRIBUTING.md) for details on how to get started.\n\nFor major changes or if you're unsure about something, please open an issue first to discuss your proposed changes.\n\n## Credits\n\nThis repo draws heavily from [phoenix-js](https://github.com/phoenixframework/phoenix/tree/master/assets/js/phoenix).\n\n## License\n\nMIT.","users":{}}
![\"Supabase](\"https://raw.githubusercontent.com/supabase/supabase/master/packages/common/assets/images/logo-preview.jpg\"){kind=logo}
\n