Skip to Content
DocsFeaturesIntegrationsNext.js AdminQuick Start

Quick Start

Get your Next.js admin dashboard running in just 5 minutes.

Prerequisites

Before you begin, ensure you have:

  • Django-CFG installed and configured
  • Node.js 18+ and pnpm/npm/yarn installed
  • A Next.js project (or use our starter template)

Need a Next.js Project?

If you don’t have a Next.js project yet, you can clone our starter template:

git clone https://github.com/django-cfg/nextjs-admin-template

Step 1: Configure Django

Add Next.js admin configuration to your Django config:

api/config.py
from django_cfg import DjangoConfig, NextJsAdminConfig
 
config = DjangoConfig(
    project_name="My Project",
    secret_key="your-secret-key",
 
    # Add Next.js admin integration
    nextjs_admin=NextJsAdminConfig(
        project_path="../django_admin",  # Path to your Next.js project
    ),
 
    # ... rest of your configuration
)

Smart Defaults

With just project_path, django-cfg automatically configures:

  • API output path: apps/admin/src/api/generated
  • Static output: out/
  • Dev server: http://localhost:3001
  • Production URL: /cfg/admin/

Step 2: Generate API Clients

Generate TypeScript clients from your Django APIs:

python manage.py generate_clients --typescript

This command will:

  1. ✅ Generate TypeScript client code from your Django APIs
  2. ✅ Copy generated clients to your Next.js project (always)
  3. ✅ Prompt to build Next.js static export (confirm with Y)
  4. ✅ Create ZIP archive for production deployment (if built)

Output Example

$ python manage.py generate_clients --typescript
 
Generating API clients...
✅ Generated TypeScript clients
   → openapi/clients/typescript/
 
Copying to Next.js project...
✅ Copied to ../django_admin/apps/admin/src/api/generated/
 
Building Next.js...
✅ Next.js build complete
   → out/ (5.2MB)
 
Creating ZIP archive...
✅ Created static/nextjs_admin.zip (7.2MB)
 
Done! Your Next.js admin is ready.

Step 3: Run Development Servers

Run both Django and Next.js dev servers:

Split Terminal

# Terminal 1: Django
python manage.py runserver
 
# Terminal 2: Next.js (with hot reload)
cd ../django_admin/apps/admin && pnpm dev

Using tmux

# Create tmux session
tmux new -s django-admin
 
# Split window
Ctrl+B %
 
# Terminal 1: Django
python manage.py runserver
 
# Switch pane
Ctrl+B →
 
# Terminal 2: Next.js
cd ../django_admin/apps/admin && pnpm dev

Using Makefile

Makefile
.PHONY: dev
 
dev:
	@echo "Starting Django and Next.js..."
	python manage.py runserver & \
	cd ../django_admin/apps/admin && pnpm dev
make dev

Option B: Production Mode (Test Production Build Locally)

Build and serve the static Next.js build:

# 1. Build Next.js
cd ../django_admin/apps/admin
pnpm build
 
# 2. Run Django (serves static build)
cd ../../..
python manage.py runserver

Step 4: Access Your Admin

Open your browser and navigate to:

http://localhost:8000/admin/

You should see:

  1. Tab 1: Built-in Dashboard - Django-CFG’s default admin
  2. Tab 2: Next.js Admin - Your custom Next.js dashboard

First Load

On the first request in production mode, django-cfg automatically extracts the ZIP archive. This may take ~100ms. Subsequent requests are instant.

Verify Everything Works

Check Authentication

The Next.js admin should automatically receive JWT tokens:

In Next.js app - src/utils/auth.ts
// Tokens are automatically injected by Django
const token = localStorage.getItem('auth_token');
const refreshToken = localStorage.getItem('refresh_token');
 
console.log('Token available:', !!token); // Should be true

Check API Connectivity

Test that your Next.js app can call Django APIs:

src/components/Dashboard.tsx
import { ProfilesClient } from '@/api/generated/profiles/client';
 
export default function Dashboard() {
  const client = new ProfilesClient();
 
  // This should work out of the box
  const data = await client.getProfile();
 
  return <div>{data.name}</div>;
}

Next Steps

🎨 Customize Configuration

Learn about all configuration options:

nextjs_admin=NextJsAdminConfig(
    project_path="../django_admin",
    dev_url="http://localhost:3002",  # Custom port
    iframe_route="/dashboard",         # Custom route
    tab_title="My Admin",              # Custom title
)

Configuration Reference →

🚀 Deploy to Production

Deploy your admin with Docker:

# Copy ZIP archive
COPY static/nextjs_admin.zip /app/static/
 
# Auto-extracts on first request

Deployment Guide →

Troubleshooting

Next.js Admin Tab Not Showing

Problem: Only the built-in dashboard tab appears.

Solution: Ensure NextJsAdminConfig is configured:

# Make sure this is set
nextjs_admin=NextJsAdminConfig(
    project_path="../django_admin",
)

iframe Not Loading

Problem: iframe shows blank page or errors.

Development Mode

Check: Is Next.js dev server running?

cd ../django_admin/apps/admin && pnpm dev

Check: Is dev server on correct port?

# Should show: Local: http://localhost:3001

Production Mode

Check: Does ZIP archive exist?

ls -lh static/nextjs_admin.zip
# Should show file ~5-10MB

Check: Logs for extraction errors:

# Should show: "Successfully extracted nextjs_admin.zip"
python manage.py runserver

API Calls Failing

Problem: Next.js app can’t call Django APIs.

Solution: Check CORS settings:

api/config.py
config = DjangoConfig(
    # ... other settings
 
    # Allow localhost for development
    cors_allowed_origins=[
        "http://localhost:3001",  # Next.js dev server
        "http://127.0.0.1:3001",
    ],
)

Common Commands Reference

# Generate TypeScript clients
python manage.py generate_clients --typescript
 
# Run Django server
python manage.py runserver
 
# Run Next.js dev server
cd ../django_admin/apps/admin && pnpm dev
 
# Build Next.js for production
cd ../django_admin/apps/admin && pnpm build
 
# Check ZIP archive was created
ls -lh static/nextjs_admin.zip

Need Help?

Join the Community

Have questions? Join our Discord or open an issue on GitHub.

OverviewCreating Custom Admin