Add django-sio to an existing Django project

This guide shows the minimal changes needed to add Socket.IO to a project that already has normal Django views.

1. Install dependencies

pip install django-sio

2. Enable Channels

In settings:

INSTALLED_APPS = [
    "daphne",
    # ... existing apps ...
    "channels",
    "myapp",
]

ASGI_APPLICATION = "your_project.config.asgi.application"

CHANNEL_LAYERS = {
    "default": {"BACKEND": "channels.layers.InMemoryChannelLayer"}
}

Use Redis or another process-safe channel layer for production broadcasting.

3. Add a consumer

from sio import SocketIOConsumer

class NotificationsConsumer(SocketIOConsumer):
    namespace = "/notifications"

    async def connect(self, socket, auth):
        await socket.join("notifications")
        return True

    async def event_ping(self, socket, payload, ack=None):
        if ack is not None:
            await ack({"status": "ok"})

4. Route Socket.IO before Django HTTP fallback

import os

from django.core.asgi import get_asgi_application
from django.urls import re_path

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "your_project.settings")
django_app = get_asgi_application()

from channels.auth import AuthMiddlewareStack
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.security.websocket import AllowedHostsOriginValidator

from myapp.consumers import NotificationsConsumer

socketio_patterns = [
    re_path(r"^socket\.io/?$", NotificationsConsumer.as_asgi()),
]

application = ProtocolTypeRouter(
    {
        "websocket": AllowedHostsOriginValidator(
            AuthMiddlewareStack(URLRouter(socketio_patterns))
        ),
        "http": AuthMiddlewareStack(
            URLRouter(socketio_patterns + [re_path("", django_app)])
        ),
    }
)

5. Connect a client

const socket = io("https://example.com", {
  path: "/socket.io",
  transports: ["websocket", "polling"],
});

const notifications = socket.io.socket("/notifications");

notifications.emit("ping", {}, (ack) => {
  console.log(ack);
});