How querateam/django-nextjs works
Project type and purpose
• This is an open-source Django app (Python package) whose sole purpose is to integrate Next.js frontend pages into a Django project by acting as an ASGI middleware and URL-based proxy.
• It lets Django handle initial HTTP and WebSocket requests for Next.js pages (including fast-refresh pipelines) and optionally proxies Next.js assets in development, while in production you delegate asset handling to a standard reverse proxy (e.g., Nginx).
File-structure analysis
• Top-level files: setup.py/pyproject.toml (package metadata), README.md, LICENSE, tests/, .github/ (CI).
• Core package directory: django_nextjs/
• asgi.py: defines NextJsMiddleware that wraps your ASGI app
• proxy.py: HTTP and WebSocket proxy consumers
• views.py & urls.py: nextjs_page view factory and URL inclusion
• render.py: logic for streaming vs. non-streaming HTML responses
• templates/django_nextjs/document_base.html: base HTML template for injection
• app_settings.py, utils.py, exceptions.py: configuration and helper routines
• tests/: unit tests for render, middleware, template integration
README insights
a. Development (Django dev server proxies Next.js dev server, handles fast-refresh)
b. Production (use external reverse proxy for Next.js assets, Django only routes page requests)
• Configuration via NEXTJS_SETTINGS for server URL, CSRF injection, public subdirectory
• Usage patterns: ASGI middleware or URL inclusion fallback, streaming flag for App Router
Main components
• Browser (client)
• Django ASGI application
• NextJsMiddleware (HTTP & WebSocket entrypoint)
• Django URL router (routes “/my/page” to nextjs_page view)
• Template engine (for document_base.html injection if customizing)
• Next.js server (dev on :3000 or prod standalone)
• .next/static and public assets
• (Optional in production) Reverse proxy server (Nginx/Caddy) for static paths
• Settings store (NEXTJS_SETTINGS)
Component relationships and data flow
• Browser → HTTP GET “/some-next-page” → Django ASGI
→ NextJsMiddleware forwards to Next.js server (nextjs_server_url)
← HTML response streams back through middleware (render logic applies)
← Final HTML returned to Browser
• Browser → WebSocket (/_next/webpack-hmr) → Django ASGI
→ NextJsMiddleware forwards to Next.js WS endpoint
→ Middleware pipes WS frames back to Browser (fast refresh)
• In DEBUG mode: Browser → “/_next/static/…” → Django ASGI
→ NextJsMiddleware proxies asset requests to Next.js
• In PRODUCTION: Browser → “/_next/static/…” → Nginx serves from .next/static
Browser → “/_next/…” → Nginx proxies to Next.js
Browser → “/next/…” → Nginx serves from public/next
Architectural patterns and design principles
• Middleware pattern: NextJsMiddleware wraps any ASGI application
• Proxy pattern: HTTPConsumer / WebSocketConsumer to transparently forward requests
• Template-injection extension point: document_base.html + customize via blocks
• Configuration-driven behavior (NEXTJS_SETTINGS dictionary)
Essential elements to capture
• Two modes of operation (DEBUG vs production)
• Settings injection (NEXTJS_SETTINGS)
• Template-injection extension point
• HTTP vs WebSocket proxying