Realtime websocket-based listeners are implemented in Frappe CRM

Frappe CRM Realtime.md

Realtime websocket-based listeners are implemented in Frappe CRM

🔌 Realtime WebSocket Implementation in Frappe CRM

1. Socket Initialization (src/socket.js)

The app initializes a Socket.IO connection that connects to the Frappe realtime server:

export function initSocket() {
  let host = window.location.hostname
  let siteName = window.site_name
  let port = window.location.port ? `:${socketio_port}` : ''
  let protocol = port ? 'http' : 'https'
  let url = `${protocol}://${host}${port}/${siteName}`

  let socket = io(url, {
    withCredentials: true,
    reconnectionAttempts: 5,
  })
  socket.on('refetch_resource', (data) => {
    if (data.cache_key) {
      let resource =
        getCachedResource(data.cache_key) ||
        getCachedListResource(data.cache_key)
      if (resource) {
        resource.reload()
      }
    }
  })
  return socket
}

Key features:

• Reads socketio_port from Frappe config
• Multi-tenant support via site namespace (/${siteName})
• Automatic resource refetching via refetch_resource event
• Integrates with frappe-ui's resource caching system

2. Global Socket Access (src/main.js)

The socket is made globally available throughout the Vue app:

let socket
if (import.meta.env.DEV) {
  frappeRequest({ url: '/api/method/crm.www.crm.get_context_for_dev' }).then(
    (values) => {
      for (let key in values) {
        window[key] = values[key]
      }
      socket = initSocket()
      app.config.globalProperties.$socket = socket
      app.mount('#app')
    },
  )
} else {
  socket = initSocket()
  app.config.globalProperties.$socket = socket
  app.mount('#app')
}

3. Store-Level Access (src/stores/global.js)

Stores provide centralized access to the socket:

import { defineStore } from 'pinia'
import { getCurrentInstance, ref } from 'vue'

export const globalStore = defineStore('crm-global', () => {
  const app = getCurrentInstance()
  const { $dialog, $socket } = app.appContext.config.globalProperties

  // ... other store logic
  
  return {
    $dialog,
    $socket,
    // ... other exports
  }
})

4. Component-Level Usage

Example 1: Notifications (src/components/Notifications.vue)

onMounted(() => {
  $socket.on('crm_notification', () => {
    notificationsStore().notifications.reload()
  })
})

onBeforeUnmount(() => {
  $socket.off('crm_notification')
})

Example 2: WhatsApp Messages (src/components/Activities/Activities.vue)

onMounted(() => {
  $socket.on('whatsapp_message', (data) => {
    if (
      data.reference_doctype === props.doctype &&
      data.reference_name === doc.value.data.name
    ) {
      whatsappMessages.reload()
    }
  })
})

onBeforeUnmount(() => {
  $socket.off('whatsapp_message')
})

5. Backend Event Publishing (Python)

Notifications (crm/fcrm/doctype/crm_notification/crm_notification.py)

class CRMNotification(Document):
    def on_update(self):
        frappe.publish_realtime("crm_notification")

WhatsApp Messages (crm/api/whatsapp.py)

def on_update(doc, method):
    frappe.publish_realtime(
        "whatsapp_message",
        {
            "reference_doctype": doc.reference_doctype,
            "reference_name": doc.reference_name,
        },
    )

6. Automatic Resource Refetching

Resources created with a cache key can be automatically refetched from the backend:

const lead = createResource({
  url: 'crm.fcrm.doctype.crm_lead.api.get_lead',
  params: { name: props.leadId },
  cache: ['lead', props.leadId],  // Cache key enables auto-refetch
  auto: true,
})

When the backend calls:

frappe.publish_realtime('refetch_resource', {'cache_key': ['lead', 'LEAD-001']})

The socket handler automatically finds and reloads the matching resource.

📊 Architecture Summary

┌─────────────────────────────────────────────────────────┐
│                     Vue Frontend                         │
│                                                          │
│  ┌──────────────┐    ┌──────────────┐                  │
│  │  Component   │───▶│  $socket.on  │                  │
│  │  (Mounted)   │    │  (listener)  │                  │
│  └──────────────┘    └──────────────┘                  │
│                             │                            │
│                             ▼                            │
│                    ┌─────────────────┐                  │
│                    │  socket.io-client│                 │
│                    └─────────────────┘                  │
└────────────────────────────┬────────────────────────────┘
                             │ WebSocket
                             │
                             ▼
┌─────────────────────────────────────────────────────────┐
│              Frappe SocketIO Server (Node.js)           │
│                     /realtime                            │
│                                                          │
│  • Multi-tenant (namespaced by site)                    │
│  • Redis pub/sub integration                            │
│  • Cookie/Token authentication                          │
└────────────────────────────┬────────────────────────────┘
                             │ Redis Pub/Sub
                             │
                             ▼
┌─────────────────────────────────────────────────────────┐
│                  Frappe Backend (Python)                │
│                                                          │
│  frappe.publish_realtime('event_name', data)           │
│  frappe.publish_progress(...)                          │
└─────────────────────────────────────────────────────────┘

🎯 Key Patterns Used

1. Global Socket Instance: Socket is initialized once and made globally available
2. Lifecycle Management: Always clean up listeners in onBeforeUnmount
3. Filtered Events: Components filter events based on context (e.g., checking doctype/name)
4. Resource Reloading: Trigger resource.reload() on realtime events
5. Cache-based Auto-refetch: Resources with cache keys can be auto-refetched
6. Backend Hooks: Use DocType hooks (on_update, etc.) to publish realtime events

This implementation follows Frappe's realtime documentation and integrates seamlessly with frappe-ui's resource management system!