Core Concepts
The Problem We Solve
Traditional Django Admin Pain Points
The gap: Django Admin is great for 90% of tasks, but hits a ceiling for complex requirements.
The django-cfg Solution
Three-in-One Architecture
One codebase, three interfaces:
- 🌐 Public (
/) - Marketing, landing pages - 👤 User Dashboard (
/private) - User features - ⚙️ Admin Panel (
/admin) - Management interface
Instead of maintaining 3 separate projects, you get shared components, shared layouts, and shared API clients - all in one Next.js monorepo.
Dual Admin Strategy
Best of Both Worlds
When to Use Each Tab
| Scenario | Use Tab 1 (Built-in) | Use Tab 2 (Next.js) |
|---|---|---|
| Simple CRUD | ✅ Perfect | ❌ Overkill |
| Quick edits | ✅ Fast | ❌ Slower |
| Custom dashboard | ❌ Limited | ✅ Unlimited |
| Real-time data | ❌ No WebSocket | ✅ Full WebSocket |
| Complex forms | ❌ Django forms | ✅ React components |
| Data visualization | ❌ Basic | ✅ Charts/Graphs |
| Mobile responsive | ⚠️ Limited | ✅ Fully responsive |
Start with Tab 1 for quick wins, graduate to Tab 2 when you need more power. No migration needed - both coexist!
Automatic API Generation
Zero-Config TypeScript Clients
What You Get
// ✅ Auto-generated from Django models
import { OrdersClient, Order } from '@/api/generated/orders';
const client = new OrdersClient();
// ✅ Full TypeScript support
const orders: Order[] = await client.list();
// ✅ Type-safe parameters
const order = await client.get(123);
// ✅ Validated payloads
await client.create({
title: "New Order",
price: 99.99,
// ❌ TypeScript error if invalid fields
});
Zero manual work - types stay in sync with Django automatically!
Authentication Flow
Seamless JWT Integration
Zero configuration needed - authentication "just works"!
- Tokens are only injected for authenticated users
- Tokens include user permissions and expiry
- iframe uses restrictive sandbox attributes
Development vs Production
Auto-Detection Magic
How it works:
- Django checks if
DEBUG=True - Quick socket test (0.1s) to see which ports are open:
- Port 3000 available → Tab 2 shows dev server ✅
- Port 3001 available → Tab 1 shows dev server ✅
- No env variables needed - automatic detection!
Just run make dev-admin or make dev - Django figures it out automatically!
Deployment Architecture
ZIP-Based Distribution
Why ZIP Instead of Direct Copy?
| Metric | Uncompressed | ZIP Archive |
|---|---|---|
| File size | ~20MB | ~7MB |
| Docker layer size | ~25MB | ~8MB |
| Files to copy | ~3000 files | 1 file |
| Build time | ~30s | ~5s |
| First request penalty | 0ms | ~100ms (once) |
| Subsequent requests | Fast | Fast (cached) |
Winner: ZIP! Smaller images, faster builds, one-time extraction cost.
Theme Synchronization
Cross-iframe Communication
Bidirectional sync:
- Django changes theme → Next.js updates ✅
- Next.js changes theme → Django updates ✅
File Structure Philosophy
Monorepo Organization
django_admin/ # ONE Next.js project
├── apps/
│ └── admin/
│ ├── pages/
│ │ ├── index.tsx # 🌐 Public: Landing page
│ │ ├── auth.tsx # 🌐 Public: Login
│ │ ├── legal/ # 🌐 Public: Terms, Privacy
│ │ │ ├── privacy.tsx
│ │ │ └── terms.tsx
│ │ ├── private/ # 👤 User Dashboard
│ │ │ ├── index.tsx
│ │ │ ├── profile.tsx
│ │ │ └── payments.tsx
│ │ └── admin/ # ⚙️ Admin Panel
│ │ ├── index.tsx
│ │ ├── crypto.tsx
│ │ └── trading.tsx
│ │
│ └── src/
│ ├── components/ # 🔁 SHARED across all
│ │ ├── ui/
│ │ └── forms/
│ ├── layouts/ # 🔁 SHARED layouts
│ │ ├── PublicLayout.tsx
│ │ ├── PrivateLayout.tsx
│ │ └── AdminLayout.tsx
│ └── api/generated/ # 🔁 SHARED API clients
│ ├── orders/
│ └── profiles/
Key insight: Everything is shared - write once, use everywhere!
One Button component works in:
- Public landing page
- User dashboard
- Admin panel
No duplication!
Scalability Model
From Startup to Enterprise
Growth path:
- Start simple - Use built-in admin (Tab 1)
- Add features - Build custom UI (Tab 2)
- Scale up - Multiple Next.js apps (future)
No migration, no rewrites - just progressive enhancement!
Comparison Matrix
vs Other Solutions
| Feature | django-cfg | Django Unfold | React Admin | Retool |
|---|---|---|---|---|
| Django integration | ✅ Native | ✅ Native | ⚠️ Manual | ❌ External |
| TypeScript | ✅ Auto-generated | ❌ No | ✅ Manual | ⚠️ Limited |
| Built-in + Custom | ✅ Both | ✅ Built-in only | ❌ Custom only | ❌ External only |
| Hot reload | ✅ Yes | ❌ No | ✅ Yes | ⚠️ Cloud only |
| Zero config | ✅ Yes | ✅ Yes | ❌ Complex | ⚠️ WYSIWYG |
| Cost | ✅ Free | ✅ Free | ✅ Free | ❌ $$$$ |
| Customization | ✅ Unlimited | ⚠️ Limited | ✅ High | ⚠️ Locked-in |
| WebSocket | ✅ Yes | ❌ No | ⚠️ Manual | ✅ Yes |
| Docker ready | ✅ Yes | ✅ Yes | ⚠️ Manual | ❌ Cloud |
| Multi-tenant | ✅ Planned | ❌ No | ⚠️ Manual | ✅ Yes |
Core Principles
1. Convention over Configuration
# All you need:
nextjs_admin=NextJsAdminConfig(
project_path="../django_admin",
)
# Everything else has smart defaults!
2. Progressive Enhancement
Start with basics → Add features → Scale up
No big rewrites, no migrations.
3. Zero Lock-in
// It's just Next.js + Django
// No proprietary APIs
// Standard tech stack
// Easy to eject if needed
4. Developer Experience First
- Hot reload in development
- Auto-generated types from Django
- Instant feedback loops
- Zero configuration magic
Real-World Example
E-commerce Platform Evolution
Timeline:
- Day 1-30: Built-in admin for products (Tab 1)
- Day 31-75: Custom sales dashboard (Tab 2)
- Day 76-105: Real-time analytics with WebSocket
- Day 106+: Scale with multiple admins
Total cost: $0 (open source) Total rewrites: 0 (incremental) Developer happiness: 💯
Next Steps
Now that you understand the why and how, let's get practical:
🚀 Quick Start
Get your first Next.js admin running in 5 minutes.
🔧 How It Works
Deep dive into the technical implementation.
Philosophy
We believe admin interfaces should be:
- Fast to start - Zero config, smart defaults
- Easy to customize - Unlimited React power when needed
- Free to scale - No lock-in, no rewrites
- Fun to build - Great DX with hot reload and TypeScript
Not just another admin framework - it's a complete full-stack solution for Django + Next.js.