django-mvp

Get your Django project to a minimum viable product — fast. django-mvp gives you a polished, settings-configurable application layout (DaisyUI 5 + Tailwind CSS v4), a library of reusable django-cotton UI components, and enhanced class-based views with search, ordering and pagination out of the box. Things should just work.

Note: django-mvp is in active development (0.x). Import paths and component APIs may change between minor versions — see the CHANGELOG.

Contents

• What you get
• Scope & philosophy
• Quick start
• Configure the layout from settings
• Views in one line each
• Menus in Python
• Optional integrations
• Styling & Theming
• Documentation
• Requirements
• Contributing
• License
• Acknowledgments

What you get

• A complete app shell — sidebar, navbar, content area, footer, and mobile dock navigation, rendered around every page and configured from Django settings (pydata-sphinx-theme style): sidebar collapse breakpoint, offcanvas vs. icon-rail collapse, and navbar widgets are all MVP_CONFIG keys.
• A Cotton component library — cards, grids, menu entries, dropdowns, pagination, hero sections and more, with small consistent attribute APIs. The basic components, such as the button, the alert and the menu, come from daisy-cotton, which is installed with it. Need more control? Override the component's template in your project — that's the intended extension path, not a bigger API.
• Views that do the boring parts — list pages with admin-style search, whitelisted ordering and pagination; form pages rendered with crispy-forms; delete flows with related-object summaries and type-to-confirm; styled error pages.
• Menus in Python — sidebar and mobile-dock navigation via django-flex-menus, with active states, icons and badges handled for you.
• Icons by name — every icon resolves through django-easy-icons; swap the icon set from settings without touching templates.
• Installable as an app — one setting and one URL include give the browser a manifest, icons and a service worker, so visitors can add the site to their home screen.
• No build tooling required — a prebuilt stylesheet ships with the package. When your own templates need their own Tailwind classes, one management command generates the build config.

Scope & philosophy

django-mvp is an application UI framework for the Django apps you write yourself. It gives you the application chrome, a library of components, and views that carry a model through to a working set of pages, so that reaching a minimum viable product doesn't start with building a UI layer.

It also fills in where Django stops. Django ships the backend machinery for formsets and leaves you with nothing to render or drive them with, so this package renders them for you, with the same look, validation and error placement every other page gets. Closing that kind of gap is squarely the point of it.

Use it for admin dashboards, data-management tools, research portals, internal apps and SaaS back-offices: anywhere you want a production-looking, data-centric Django application without writing the front end first.

What it deliberately is not:

• An admin theme. It doesn't touch django.contrib.admin. django-unfold and django-daisy serve that audience well.
• A component engine. django-cotton provides the syntax; this package provides components built with it.
• A project scaffold. You install it as a dependency and upgrade it, rather than generating a starter project you then own outright.
• An authentication system. It provides the Account Center, the area itself, and development-only sign-in and sign-out pages so a guarded page is reachable while you build. Full account management — sign-up, password and multi-factor flows, and production-ready sign-in and sign-out — still lives in django-accounts-center, which builds on these components.
• A JavaScript application. Pages are server-rendered, with Alpine and htmx where interaction calls for it. No build step, no single-page frontend.
• An API layer. Django REST Framework and django-ninja already cover that ground.
• Real-time infrastructure. Websockets and Channels are out of scope.

Principles, in the order they settle a close call:

1. Things should just work. Sensible defaults, minimum ceremony, MVP first.
2. Configuration before customization. Views are configured declaratively, much as Django's admin classes are. When the packaged look isn't right, override the Cotton component and honour its attributes. Past that, bring your own CSS.
3. Basic components, not a component framework. Small attribute APIs and limited variation. A component earns its place here by being useful more than once, and a specialized one belongs in a package of its own. Cotton finds components in any installed app, so a component pack needs no registration.
4. Integrate, don't reimplement. Django's third-party ecosystem already covers a great deal of this ground, but most of those packages still leave you to adapt their output into your own templates before it looks like part of your application. Rather than rewriting well-established packages, django-mvp puts a consistent UI around them wherever it can.

Where the package is headed is a separate question, answered in GOALS.md.

Quick start

pip install django-mvp

# settings.py
INSTALLED_APPS = [
    ...
    "your_app",         # your apps above "mvp", see below
    "django.contrib.sites",
    "django_cotton",
    "easy_icons",
    "flex_menu",
    "mvp",
    "daisy_cotton",     # installed with django-mvp, listed below "mvp"
    "crispy_forms",
    "mvp_forms",        # the daisyUI template pack forms are drawn with
]

Order matters here. Django's template loader walks INSTALLED_APPS top to bottom and takes the first copy of a name it finds, so list your own apps above mvp to override any template django-mvp ships. This is the same rule projects already use to override the Django admin's templates. Keep daisy_cotton below mvp for the same reason: both ship an icon component, and the one in mvp must be found first.

See Getting Started for the rule in full.

# settings.py, continued

TEMPLATES = [{
    ...
    "OPTIONS": {"context_processors": [
        ...
        "mvp.context_processors.mvp_config",
    ]},
}]

EASY_ICONS = {
    "default": {
        "renderer": "easy_icons.renderers.ProviderRenderer",
        "config": {"tag": "i"},
        "packs": ["mvp.utils.BS5_ICONS"],   # icons used by mvp's own components
    },
}

FLEX_MENUS = {
    "renderers": {
        "sidebar": "mvp.renderers.SidebarRenderer",
        "dock": "mvp.renderers.MobileFooterNavRenderer",
    },
}

CRISPY_ALLOWED_TEMPLATE_PACKS = ["daisyui"]
CRISPY_TEMPLATE_PACK = "daisyui"

{# templates/dashboard.html #}
{% extends "mvp/base.html" %}

{% block content %}
  <c-mvp.container>
    <c-mvp.section title="Dashboard" icon="home">
      <c-mvp.grid md="2" xl="4">
        <c-mvp.card title="Orders">150 new</c-mvp.card>
        <c-mvp.card title="Revenue">$12,400</c-mvp.card>
      </c-mvp.grid>
    </c-mvp.section>
  </c-mvp.container>
{% endblock %}

Full walkthrough: Getting Started.

Configure the layout from settings

MVP_CONFIG = {
    "layout": {
        "sidebar": {
            "breakpoint": "lg",       # sm|md|lg|xl|2xl — when the sidebar is persistent
            "collapse": "offcanvas",  # "offcanvas" (slide away) or "icons" (icon rail)
        },
        "navbar": {
            # Cotton component names, rendered at the right end of the navbar
            "end": ["mvp.actions.theme-controller", "mvp.actions.language-switcher"],
        },
    },
}

Per-page overrides use component attributes (<c-mvp.app breakpoint="xl">, <c-mvp.app.sidebar collapse="icons">). Details: Layout.

Views in one line each

from mvp.views import MVPListView, MVPCreateView, MVPUpdateView, MVPDeleteView


class ProductListView(MVPListView):
    model = Product
    search_fields = ["name", "description"]              # ?q= multi-word search
    order_by = [("name_asc", "Name (A-Z)", "name")]      # ?o= whitelisted ordering


class ProductCreateView(MVPCreateView):
    model = Product
    fields = ["name", "category", "price"]               # crispy-detected rendering

Details: Views.

Menus in Python

# myapp/menus.py
from flex_menu import MenuItem
from mvp.menus import AppMenu

AppMenu.extend([
    MenuItem(name="dashboard", view_name="dashboard",
             extra_context={"label": "Dashboard", "icon": "home"}),
])

Details: Navigation.

Optional integrations

Views that build on third-party packages live in guarded modules — no extras, and the dependency is only required when you import the integration:

from mvp.integrations.django_tables.views import MVPTableView      # django-tables2
from mvp.integrations.django_filters.views import MVPFilteredListView  # django-filter

Details: Integrations.

Styling & Theming

Django MVP is styled with Tailwind CSS v4 + DaisyUI 5 and ships a prebuilt stylesheet with the complete DaisyUI component set and every DaisyUI theme. Most projects need no build tooling at all.

Set MVP_CONFIG["theme"]["default"] to any DaisyUI theme name (dracula, synthwave, ...) and it applies with no build step and nothing fetched from outside your project. Offer a choice of themes to visitors through MVP_CONFIG["theme"]["choices"], or write your own theme as a plain CSS file. See docs/theming.md for the full variable reference and a worked example.

If your own templates use their own Tailwind utility classes, rebuild the CSS with the generated entry file, which scans your templates, Django MVP's and daisy-cotton's:

npm install -D tailwindcss @tailwindcss/cli daisyui@^5.7
python manage.py mvp_tailwind > assets/tailwind.css
npx @tailwindcss/cli -i assets/tailwind.css -o static/css/app.css --minify

See docs/styling.md for the full guide (two-tier model, theming, and the packaged Tailwind preset).

Documentation

Start at docs/index.md: Getting Started · Configuration · Layout · Components · Navigation · Icons · Views · Formsets · Styling · Integrations · Troubleshooting. Keeping a page current is a condition of merging the change it describes, so it will not point you at an API that has moved.

Building with an AI coding assistant

skills/django-mvp/SKILL.md is a short map written for coding agents: the decisions to get right first, a quickstart, and a routing table naming the docs/ page that answers each kind of question. Point your assistant at it, or copy it into wherever it loads skills from — it links each page by URL as well as by path, so it works from a checkout or on its own. The documentation it routes into is the same documentation a person reads, which is what keeps the two from disagreeing.

Requirements

• Python 3.12+
• Django 5.2+ (currently supported Django releases, tested on 5.2, 6.0 and 6.1)
• django-cotton, django-flex-menus, django-easy-icons (installed automatically)

Contributing

Contributions are welcome. See CONTRIBUTING.md for the setup, and the testing and code documentation standards every change follows.

License

MIT License — see LICENSE.

Acknowledgments

Built with django-cotton by @wrabit, DaisyUI, Tailwind CSS, Alpine.js, htmx and Bootstrap Icons.