django-admin-forge 0.1.0

A modern, extensible, premium Django admin framework.

django-admin-forge

django-admin-forge is a modern, customizable Django admin framework for serious SaaS and enterprise apps.

It keeps Django admin's reliability and model integration, while upgrading the UI/UX, theming, and developer customization surface.

Highlights

• Django-first admin replacement (AdminSite-based)
• Branded login and modern dashboard
• Customizable sidebar menus and app/model navigation
• Dark, light, and system themes
• Accent color system
• Improved changelist, filters, bulk actions, and empty states
• Improved add/edit form layout

Install

From PyPI:

pip install django-admin-forge

If you previously tried the django-forge distribution name, switch to this package: update INSTALLED_APPS and imports to django_admin_forge, rename settings DJANGO_ADMIN_FORGE, then pip uninstall django-forge (if installed) and install as above.

From a wheel or sdist you built locally:

python -m pip install build
python -m build
pip install dist/django_admin_forge-*.whl

Develop this repository (editable install, tests, lint):

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Publishing to PyPI

1. Configure PyPI credentials (for example upload with twine or uv publish).
2. Bump version in pyproject.toml.
3. Install build tools: pip install ".[publish]" (or pip install build twine).
4. Run python -m build, then twine check dist/* and twine upload dist/*.

Use TestPyPI first if you want a dry run: twine upload --repository testpypi dist/*.

Quick Integration

1) Add apps

INSTALLED_APPS = [
    "django_admin_forge",
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    # your apps...
]

2) Use Forge admin URLs

from django.urls import path
from django_admin_forge.site import forge_admin_site

urlpatterns = [
    path("admin/", forge_admin_site.urls),
]

3) Configure DJANGO_ADMIN_FORGE (optional but recommended)

DJANGO_ADMIN_FORGE = {
    "brand_name": "Forge Admin",
    "brand_logo_text": "FORGE",
    "brand_tagline": "Modern Django operations panel",
    "accent_color": "green",
    "default_theme": "system",  # "light" | "dark" | "system"
    "show_sidebar_search": True,
    "enable_command_bar": True,
}

Configuration Reference

Use the DJANGO_ADMIN_FORGE setting dictionary.

• brand_name (str): Header brand name.
• brand_logo_text (str): Compact sidebar/logo text.
• brand_tagline (str): Login/subtitle branding.
• accent_color (str): Accent token used in key actions and highlights.
• default_theme ("light" | "dark" | "system"): Initial theme mode.
• show_sidebar_search (bool): Sidebar search input visibility.
• enable_command_bar (bool): Header search/command input visibility.
• menu_icons (dict[str, str]): Overrides for app/model icons.
• menu_tabs (list[dict]): Sidebar menu tabs (top and bottom areas).
• dashboard_analytics_cards (list[dict]): Override dashboard KPI cards for marketing/business snapshots.

Accent Colors

Supported accent_color values:

blue, green, amber, violet, emerald, teal, cyan, sky, indigo, purple, pink, rose, red, orange, yellow, lime, slate, gray, zinc, neutral, stone

Example:

DJANGO_ADMIN_FORGE = {
    "accent_color": "rose",
}

Sidebar Menus (menu_tabs)

By default, only Dashboard is shown.

You can fully configure sidebar tabs:

DJANGO_ADMIN_FORGE = {
    "menu_tabs": [
        {"label": "Dashboard", "url_name": "admin:index", "icon": "layout-grid"},
        {"label": "Applications", "url_name": "admin:forge-applications", "icon": "layers"},
        {"label": "Users", "url_name": "admin:auth_user_changelist", "icon": "user"},
        {"label": "Documentation", "url": "/docs/", "icon": "external-link"},
    ]
}

Each tab supports:

• label (required)
• url_name (reverse name) or url (direct URL)
• icon (optional, defaults to layout-grid)

Menu Icon Overrides (menu_icons)

You can override app/model icons by key:

DJANGO_ADMIN_FORGE = {
    "menu_icons": {
        "auth": "shield",                # app-level
        "auth.user": "user",             # model-level
        "auth.group": "users",
        "demo_app.customer": "building",
    }
}

Resolution order:

1. app_label.model_name
2. model_name
3. app_label
4. built-in defaults

Dashboard Analytics Cards

You can supply custom KPI cards for the dashboard hero section using real model data:

DJANGO_ADMIN_FORGE = {
    "dashboard_analytics_cards": [
        {
            "label": "Customers",
            "app_label": "demo_app",
            "model": "Customer",
            "metric": "count",
            "icon": "users",
            "hint": "Total customer records",
        },
        {
            "label": "Active customers",
            "app_label": "demo_app",
            "model": "Customer",
            "metric": "count",
            "queryset_filter": {"is_active": True},
            "icon": "activity",
            "hint": "is_active = true",
        },
    ]
}

Each card supports:

• label (required)
• app_label and model for dynamic model-based metrics
• metric (currently supports count)
• queryset_filter (optional exact Django ORM filters)
• value (optional fallback/manual value)
• icon
• hint (or trend)

Demo Project (this repo)

python demo/manage.py migrate
python demo/manage.py createsuperuser
python demo/manage.py runserver

Open: http://127.0.0.1:8000/admin/

Status and Roadmap

Current implementation includes custom site templates, dashboard, apps page, collapsible sidebar, filters modal, improved forms/changelists, search helpers, and theme controls.

Planned next:

• Saved views/filters
• Dashboard widget API expansion
• Accessibility and keyboard navigation improvements
• Packaging/build pipeline polish for production release