realtime: add page on throttling

apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts

@@ -886,6 +886,10 @@ export const realtime: NavMenuConstant = {
       name: 'Guides',
       url: undefined,
       items: [
+        {
+          name: 'Throttling messages',
+          url: '/guides/realtime/guides/client-side-throttling',
+        },
         {
           name: 'Subscribing to Database Changes',
           url: '/guides/realtime/subscribing-to-database-changes',

apps/docs/pages/guides/realtime/broadcast.mdx

@@ -245,26 +245,6 @@ channelD.subscribe(async (status) => {
 
 Use this to guarantee that the server has received the message before resolving `channelD.send`'s promise. If the `ack` config is not set to `true` when creating the channel, the promise returned by `channelD.send` will resolve immediately.
 
-## Client-side rate limit
-
-By default the client will rate limit itself at 10 messages per second (1 message every 100 milliseconds). You can customize this when creating the client:
-
-```js
-import { createClient } from '@supabase/supabase-js'
-
-const clientE = createClient('https://<project>.supabase.co', '<your-anon-key>', {
-  realtime: {
-    params: {
-      eventsPerSecond: 20,
-    },
-  },
-})
-```
-
-By setting `eventsPerSecond` to 20, you can send one message every 50 milliseconds on a per client basis.
-
-Learn more by visiting the [Quotas](/docs/guides/realtime/quotas) section.
-
 ## More Realtime Quickstarts
 
 - [Presence Quickstart](/docs/guides/realtime/presence)

apps/docs/pages/guides/realtime/guides/client-side-throttling.mdx

@@ -0,0 +1,47 @@
+import Layout from '~/layouts/DefaultGuideLayout'
+
+export const meta = {
+  id: 'realtime',
+  title: 'Throttling messages',
+  description: 'Use client-side throttling to manage message frequency.',
+  subtitle: 'Use client-side throttling to manage message frequency.',
+}
+
+You should always consider optimizing the performance of you realtime system.
+
+## Project Quotas
+
+Each Broadcast and Presence message counts towards your [Project Quotas](/docs/guides/realtime/quotas).
+
+It's common to unintentionally flood the Realtime service with messages. For example, tracking mouse movents without throttling would send hundreds of events per second. It's rare that you need so many messages. Updating a mouse movement even a few times per second is usually enough for the human eye.
+
+The Supabase client includes a configurable throttling parameter to protect against these unintended floods.
+
+## Default client throttling
+
+By default the Supabase clients throttles messages to 10 messages per-second (1 message every 100 milliseconds). This is a soft-limit provided as a safe-guard when you're getting started. You'll rarely need to send more messages than this.
+
+Each client has their own throttling behavior. For example, if you instantiate two clients, by default you would send 20 messages per-second to your project.
+
+## Managing client-side throttling
+
+You can customize the client-side throttling when creating the client:
+
+```js
+import { createClient } from '@supabase/supabase-js'
+
+const SUPABASE_URL = 'https://<project>.supabase.co'
+const SUPABASE_ANON_KEY = '<your-anon-key>'
+
+const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
+  realtime: {
+    params: {
+      eventsPerSecond: 2,
+    },
+  },
+})
+```
+
+export const Page = ({ children }) => <Layout meta={meta} children={children} />
+
+export default Page

apps/docs/pages/guides/realtime/presence.mdx

@@ -245,26 +245,6 @@ const channelC = supabase.channel('test', {
 })
 ```
 
-## Client-Side Rate Limit
-
-By default the client will rate limit itself at 10 messages per second (1 message every 100 milliseconds). You can customize this when creating the client:
-
-```js
-import { createClient } from '@supabase/supabase-js'
-
-const supabase = createClient('https://<project>.supabase.co', '<your-anon-key>', {
-  realtime: {
-    params: {
-      eventsPerSecond: 5,
-    },
-  },
-})
-```
-
-By setting `eventsPerSecond` to 5, you can send one message every 200 milliseconds on a per client basis.
-
-Learn more by visiting the [Quotas](/docs/guides/realtime/quotas) section.
-
 ## More Realtime Quickstarts
 
 - [Broadcast Quickstart](/docs/guides/realtime/broadcast)