ChanX: A Type-Safe Framework Built on Django Channels

Show & Tell
1

Hello Django community,

I’d like to introduce ChanX, a framework built on top of Django Channels that brings automatic routing, type safety, and AsyncAPI documentation to WebSocket development. After years of working with Channels in production, I found myself repeatedly implementing the same patterns, so I built ChanX to provide these as a framework layer.

The Problem

Typical Django Channels code requires manual routing and validation:

async def receive_json(self, data):
    action = data.get("action")
    if action == "chat":
        if not isinstance(data.get("payload"), str):
            await self.send_json({"error": "Invalid payload"})
            return
        # ... handle chat
    elif action == "ping":
        await self.send_json({"action": "pong"})
    # ... endless elif chains

Pain points: manual if-else chains, no type safety, no auto-documentation (unlike Django REST framework), inconsistent team patterns.

The Solution

ChanX provides decorator-based patterns similar to Django REST framework:

from typing import Literal
from chanx.messages.base import BaseMessage
from chanx.core.decorators import ws_handler, channel
from chanx.channels.websocket import AsyncJsonWebsocketConsumer

class ChatMessage(BaseMessage):
    action: Literal["chat"] = "chat"
    payload: str

@channel(name="chat")
class ChatConsumer(AsyncJsonWebsocketConsumer):
    groups = ["chat_room"]

    @ws_handler
    async def handle_chat(self, msg: ChatMessage) -> None:
        await self.broadcast_message(
            ChatNotification(payload=NotificationPayload(
                message=msg.payload,
                timestamp=datetime.now()
            ))
        )

    @ws_handler
    async def handle_ping(self, msg: PingMessage) -> PongMessage:
        return PongMessage()

Key Features

  • Automatic routing via Pydantic discriminated unions - no if-else chains
  • Type safety with full mypy/pyright support and Pydantic validation
  • AsyncAPI 3.0 documentation auto-generated from decorators
  • DRF authentication integration with built-in DjangoAuthenticator
  • Event broadcasting from anywhere (views, Celery tasks, management commands)
  • Testing utilities including WebsocketTestCase and type-safe helpers
  • Django settings integration with per-consumer overrides

Tutorial & Documentation

I’ve created a comprehensive hands-on tutorial that builds a real chat app with AI assistants, notifications, and background tasks. The tutorial uses a Git repository with checkpoints so you can start anywhere or compare implementations.

Installation:

pip install "chanx[channels]"

Project Status

ChanX is production-ready with comprehensive test coverage, full type checking (mypy/pyright), and complete documentation. It’s actively maintained and used in production.

I’d love to hear feedback from the Django community on useful patterns to add or use cases to better support. Happy to answer questions about implementation or design decisions.

Thank you, and I hope ChanX helps make WebSocket development in Django more productive.

2 Likes