Django-CFG vs Alternatives: Complete Comparison Guide

# settings.py
import environ
 
env = environ.Env(
    DEBUG=(bool, False),
    DATABASE_URL=(str, 'sqlite:///db.sqlite3')
)
 
# Read .env file
environ.Env.read_env()
 
# Configure database
DEBUG = env('DEBUG')  # Runtime casting to bool
DATABASES = {
    'default': env.db('DATABASE_URL')  # Parses DATABASE_URL string
}
 
# Issues:
# - No startup validation (wrong URL format fails at connection time)
# - No IDE autocomplete for env('DEBUG')
# - Type casting errors silent until runtime
# - Can't tell what config is required vs optional

# config.py
from django_cfg import DjangoConfig, DatabaseConfig
from typing import Dict
from .environment import env
 
class MyConfig(DjangoConfig):
    """Type-safe configuration with validation"""
 
    debug: bool = False  # Pydantic validates boolean
    databases: Dict[str, DatabaseConfig] = {
        "default": DatabaseConfig(
            engine="django.db.backends.postgresql",
            name=env.database.name,      # Already validated from YAML
            host=env.database.host,      # Type-safe: str
            port=env.database.port,      # Type-safe: int
        )
    }
 
# Benefits:
# ✅ Startup validation (fails before Django loads if invalid)
# ✅ Full IDE autocomplete (env.database.<TAB> shows fields)
# ✅ Type safety (port is int, not string)
# ✅ Self-documenting (field descriptions as hints)

# settings.py - Manual CORS setup
ALLOWED_HOSTS = env.list('ALLOWED_HOSTS', default=['localhost'])
 
CORS_ALLOWED_ORIGINS = [
    f"https://{host}" for host in ALLOWED_HOSTS
    if host not in ['localhost', '127.0.0.1']
]
CORS_ALLOW_CREDENTIALS = True
CSRF_TRUSTED_ORIGINS = CORS_ALLOWED_ORIGINS
SECURE_CROSS_ORIGIN_OPENER_POLICY = "same-origin-allow-popups"
 
# Issues:
# - 5+ separate settings to manage
# - Easy to forget one setting
# - No validation of host format
# - Requires django-cors-headers package

# config.py - Single field auto-generates all CORS settings
class MyConfig(DjangoConfig):
    security_domains: list[str] = ["myapp.com", "www.myapp.com"]
 
    # Auto-generates:
    # - ALLOWED_HOSTS
    # - CORS_ALLOWED_ORIGINS (with https://)
    # - CORS_ALLOW_CREDENTIALS
    # - CSRF_TRUSTED_ORIGINS
    # - SECURE_CROSS_ORIGIN_OPENER_POLICY
    # - SECURE_SSL_REDIRECT (in production)
    # - SECURE_HSTS_SECONDS
    # All validated and consistent
 
# Benefits:
# ✅ 1 field → 7+ Django settings
# ✅ No manual CORS package configuration
# ✅ Impossible to have inconsistent CORS/CSRF settings

# BEFORE: django-environ
import environ
env = environ.Env()
DEBUG = env.bool('DEBUG', default=False)
DATABASES = {'default': env.db('DATABASE_URL')}
 
# AFTER: Django-CFG
from django_cfg import DjangoConfig, DatabaseConfig
from .environment import env  # Pydantic YAML loader
 
class MyConfig(DjangoConfig):
    debug: bool = env.debug  # Type-safe from YAML
    databases: Dict[str, DatabaseConfig] = {
        "default": DatabaseConfig(
            name=env.database.name,
            # ... other fields
        )
    }

# settings.py - Traditional approach
INSTALLED_APPS = [
    'django.contrib.admin',
    'corsheaders',  # Need to install
    'rest_framework',  # Need to install
    'rest_framework_simplejwt',  # Need to install
    # ... manual configuration
]
 
# Manual CORS setup
CORS_ALLOWED_ORIGINS = [
    "http://localhost:3000",
    "https://yourdomain.com"
]
CORS_ALLOW_CREDENTIALS = True
CSRF_TRUSTED_ORIGINS = CORS_ALLOWED_ORIGINS
 
# Manual JWT setup
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ],
}
 
# Manual static files for Next.js build
STATICFILES_DIRS = [
    BASE_DIR / 'nextjs_build/out',
]
 
# Then manually:
# 1. Set up Next.js project structure
# 2. Configure API routes
# 3. Write TypeScript interfaces manually
# 4. Set up authentication flow
# 5. Handle theme synchronization
# 6. Configure build pipeline
# 7. Set up deployment
 
# Total: 200+ lines + multiple hours of setup

# config.py
from django_cfg import DjangoConfig, NextJsAdminConfig
 
class MyConfig(DjangoConfig):
    project_name = "My Project"
 
    # That's it! One line for full Next.js admin:
    nextjs_admin = NextJsAdminConfig(
        project_path="../django_admin",
    )
 
# Everything else is automatic:
# ✅ JWT authentication configured
# ✅ CORS settings auto-generated
# ✅ Theme sync enabled
# ✅ Static files configured
# ✅ TypeScript generation ready
# ✅ Dev mode auto-detection
# ✅ Production ZIP deployment
 
# Total: 1 line + zero manual setup

my-project/
├── django-backend/        # Django API
├── public-website/        # Landing pages (separate Next.js)
├── user-dashboard/        # User features (separate Next.js)
└── admin-panel/           # Admin UI (separate Next.js or Django admin)

Problems:
❌ 4 separate codebases to maintain
❌ Duplicate components and logic
❌ Multiple deployment pipelines
❌ Inconsistent styling and UX
❌ Complex authentication across projects

my-project/
├── django/                # Django backend + config
└── admin/                 # ONE Next.js project for everything
    ├── app/
    │   ├── (public)/      # Public website (/)
    │   ├── private/       # User dashboard (/private)
    │   └── admin/         # Admin panel (/admin)
    ├── components/        # Shared components
    ├── lib/              # Shared utilities
    └── api/              # Auto-generated TypeScript clients

Benefits:
✅ Single codebase, shared components
✅ Consistent design system
✅ One deployment pipeline
✅ Unified authentication
✅ Easy code reuse

┌─────────────────────────────────────────────────────────────┐
│                    Django Admin (Unfold)                     │
│                                                               │
│  [Tab 1: Built-in]           [Tab 2: Next.js Admin]         │
│  ┌──────────────────┐        ┌────────────────────┐         │
│  │ Quick CRUD       │        │ Complex Features    │         │
│  │ • Users          │        │ • Analytics         │         │
│  │ • Posts          │        │ • Real-time data    │         │
│  │ • Settings       │        │ • Custom workflows  │         │
│  │ (Django Unfold)  │        │ (React + Charts)    │         │
│  └──────────────────┘        └────────────────────┘         │
└─────────────────────────────────────────────────────────────┘

# One command generates everything:
python manage.py generate_clients --typescript
 
# Output:
# ✅ Generated TypeScript clients from Django models
# ✅ Copied to Next.js project
# ✅ Built Next.js static export
# ✅ Created ZIP archive (~7MB)
 
# Use in Next.js:
import { CfgClient } from '@/api/generated/cfg';
 
const client = new CfgClient();
const users = await client.users.list();  // Fully typed!

# settings.py
from decouple import config, Csv
 
DEBUG = config('DEBUG', default=False, cast=bool)
SECRET_KEY = config('SECRET_KEY')
ALLOWED_HOSTS = config('ALLOWED_HOSTS', default='localhost', cast=Csv())
 
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': config('DB_NAME'),
        'USER': config('DB_USER'),
        'PASSWORD': config('DB_PASSWORD'),
        'HOST': config('DB_HOST', default='localhost'),
        'PORT': config('DB_PORT', default=5432, cast=int),
    }
}
 
# Issues:
# - Still verbose (manual dict construction)
# - No startup validation
# - Type casting per-variable
# - No IDE hints

# config.py
from django_cfg import DjangoConfig, DatabaseConfig
from .environment import env
 
class MyConfig(DjangoConfig):
    secret_key: str = env.secret_key
    debug: bool = False
    security_domains: list[str] = ["localhost"]
 
    databases: Dict[str, DatabaseConfig] = {
        "default": DatabaseConfig(
            engine="django.db.backends.postgresql",
            name=env.database.name,
            user=env.database.user,
            password=env.database.password,
            host=env.database.host,
            port=env.database.port,
        )
    }
 
# Benefits:
# ✅ More concise (no manual dict construction)
# ✅ Type-safe (Pydantic validates all fields)
# ✅ IDE autocomplete works

# config.py
from pydantic_settings import BaseSettings
from pydantic import Field
 
class Settings(BaseSettings):
    """Generic settings (not Django-aware)"""
 
    debug: bool = False
    secret_key: str = Field(..., min_length=50)
 
    db_name: str
    db_user: str
    db_password: str
    db_host: str = "localhost"
    db_port: int = 5432
 
    class Config:
        env_file = ".env"
 
settings = Settings()
 
# Now manually convert to Django settings.py
DEBUG = settings.debug
SECRET_KEY = settings.secret_key
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',  # Manual
        'NAME': settings.db_name,
        'USER': settings.db_user,
        'PASSWORD': settings.db_password,
        'HOST': settings.db_host,
        'PORT': settings.db_port,
    }
}
# Still need to manually configure ALLOWED_HOSTS, CORS, etc.
 
# Issues:
# - No Django settings generation (manual conversion)
# - No smart defaults (have to specify everything)
# - No built-in Django features
# - 100-150 lines for full configuration

# config.py
from django_cfg import DjangoConfig, DatabaseConfig
from typing import Dict
from .environment import env
 
class MyConfig(DjangoConfig):
    """Django-aware settings with smart defaults"""
 
    secret_key: str = env.secret_key
    debug: bool = False
    security_domains: list[str] = ["localhost"]
 
    databases: Dict[str, DatabaseConfig] = {
        "default": DatabaseConfig(
            engine="django.db.backends.postgresql",
            name=env.database.name,
            user=env.database.user,
            password=env.database.password,
            host=env.database.host,
            port=env.database.port,
        )
    }
 
# In settings.py - auto-generates all Django settings
config = MyConfig()
globals().update(config.get_all_settings())
# Generates: DATABASES, ALLOWED_HOSTS, CORS_*, INSTALLED_APPS, MIDDLEWARE, etc.
 
# Benefits:
# ✅ Automatic Django settings generation
# ✅ Smart defaults (MIDDLEWARE, INSTALLED_APPS pre-configured)
# ✅ Django-specific models (DatabaseConfig, CacheConfig, etc.)
# ✅ 30-50 lines for full configuration

# BEFORE: pydantic-settings
from pydantic_settings import BaseSettings
 
class Settings(BaseSettings):
    db_name: str
    db_user: str
    # ... 20+ fields
 
settings = Settings()
 
# Manual Django conversion
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': settings.db_name,
        # ... manual mapping
    }
}
 
# AFTER: Django-CFG
from django_cfg import DjangoConfig, DatabaseConfig
 
class MyConfig(DjangoConfig):
    databases: Dict[str, DatabaseConfig] = {
        "default": DatabaseConfig(
            engine="django.db.backends.postgresql",
            name=env.database.name,
            # DatabaseConfig handles the rest
        )
    }
 
config = MyConfig()
globals().update(config.get_all_settings())  # Auto-generates DATABASES

# settings.py - 200+ lines
import os
from pathlib import Path
 
BASE_DIR = Path(__file__).resolve().parent.parent
 
# ❌ String parsing everywhere
SECRET_KEY = os.environ.get('SECRET_KEY', 'insecure-default')
DEBUG = os.environ.get('DEBUG', 'False').lower() in ('true', '1', 'yes')
 
# ❌ Manual list parsing
ALLOWED_HOSTS = os.environ.get('ALLOWED_HOSTS', 'localhost').split(',')
 
# ❌ Manual CORS configuration (multiple settings)
CORS_ALLOWED_ORIGINS = [
    f"https://{host}" for host in ALLOWED_HOSTS
    if host not in ['localhost', '127.0.0.1']
]
CORS_ALLOW_CREDENTIALS = True
CSRF_TRUSTED_ORIGINS = CORS_ALLOWED_ORIGINS
 
# ❌ Manual database configuration
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ.get('DB_NAME', 'mydb'),
        'USER': os.environ.get('DB_USER', 'postgres'),
        'PASSWORD': os.environ.get('DB_PASSWORD', ''),
        'HOST': os.environ.get('DB_HOST', 'localhost'),
        'PORT': int(os.environ.get('DB_PORT', '5432')),  # Manual int()
    }
}
 
# ... 100+ more lines for cache, email, static, templates, etc.
 
# Issues:
# - No type validation
# - No IDE autocomplete
# - Manual type conversion (can fail silently)
# - Hard to test (global variables)
# - Configuration errors only caught at runtime

# config.py - 30-50 lines
from django_cfg import DjangoConfig, DatabaseConfig
from typing import Dict
from .environment import env
 
class MyConfig(DjangoConfig):
    """Type-safe, validated configuration"""
 
    secret_key: str = env.secret_key
    debug: bool = False
    security_domains: list[str] = ["myapp.com"]
 
    databases: Dict[str, DatabaseConfig] = {
        "default": DatabaseConfig(
            engine="django.db.backends.postgresql",
            name=env.database.name,
            user=env.database.user,
            password=env.database.password,
            host=env.database.host,
            port=env.database.port,
        )
    }
 
# settings.py - 2 lines
config = MyConfig()
globals().update(config.get_all_settings())
 
# Benefits:
# ✅ 85% less code
# ✅ Type-safe (Pydantic)
# ✅ IDE autocomplete
# ✅ Validation at startup
# ✅ Easy to test (just instantiate class)

START: Evaluate your project needs

Q1: Is this a production Django application?
├─ NO → Use django-environ or settings.py
└─ YES → Continue to Q2

Q2: Do you need type safety and validation?
├─ NO → Use django-environ
└─ YES → Continue to Q3

Q3: Is this Django-only or multi-framework?
├─ Multi-framework → Use pydantic-settings
└─ Django-only → Continue to Q4

Q4: Do you need modern admin interfaces (React/Next.js)?
├─ YES → Use Django-CFG ✅ (only option with built-in Next.js)
└─ NO → Continue to Q5

Q5: Do you want built-in apps or AI features?
├─ NO → Use pydantic-settings
└─ YES → Use Django-CFG ✅

Q6: Is your team comfortable with Pydantic?
├─ NO → Use django-environ (simpler)
└─ YES → Use Django-CFG ✅

# Use django-environ for gradual migration
import environ
env_compat = environ.Env()
 
# Use Django-CFG for new configuration
from django_cfg import DjangoConfig
 
class MyConfig(DjangoConfig):
    # New config in Django-CFG
    security_domains: list[str] = ["myapp.com"]
 
config = MyConfig()
settings = config.get_all_settings()
 
# Keep legacy django-environ settings
settings['LEGACY_SETTING'] = env_compat('LEGACY_SETTING')
 
globals().update(settings)

# Export current config to settings.py
config = MyConfig()
settings_dict = config.get_all_settings()
 
# Print as Python code
for key, value in settings_dict.items():
    print(f"{key} = {repr(value)}")
 
# Copy output to new settings.py