Migration from v0.x

Version 2.0 is a major rewrite. This guide covers breaking changes when upgrading from the legacy React-based admin (v0.x).

Summary of breaking changes

Change

Migration path

React UI removed

Admin is now Jinja2 + HTMX at /admin

/admin-ui mount removed

Use mount_admin_app() → /admin

MongoAdmin alias removed

Use AdminSite or site

Built-in demo token auth removed

Provide auth_dependency

Legacy document routes removed

/admin/collections/.../documents → standard CRUD URLs

Configuration API changed

Use ModelAdmin class attributes and hooks

Step-by-step migration

1. Update installation

pip install "fastapi-mongo-admin>=2.0.0"

2. Replace mount call

Before (v0.x):

from fastapi_mongo_admin import MongoAdmin

admin = MongoAdmin(app, database)

After (v2):

from fastapi_mongo_admin import mount_admin_app, site

mount_admin_app(app, get_database, admin_site=site, mode="async")

3. Define ModelAdmin classes

v2 requires explicit ModelAdmin configuration for each model:

class ProductAdmin(ModelAdmin):
    model = Product
    collection_name = "products"
    list_display = ["name", "price"]

site.register(Product, ProductAdmin)

4. Add authentication

v2 does not include built-in token auth:

mount_admin_app(app, get_database, auth_dependency=your_auth)

5. Update URL references

v0.x

v2

/admin-ui/

/admin/

/admin/collections/{name}/documents

/admin/{collection}/

Custom React components

Jinja2 template overrides

6. Remove React-specific code

If you customized the React SPA, migrate customizations to:

  • ModelAdmin configuration (list display, filters, actions)

  • Jinja2 template overrides

  • Custom admin views via register_view()

New features in v2

Features not available in v0.x:

  • Django-style ModelAdmin with hooks and permissions

  • List filters (choice, boolean, date, related, custom)

  • Field mapping for legacy MongoDB schemas

  • Fieldsets and formfield overrides

  • Bulk actions with @action decorator

  • list_select_related for reference display

  • Date hierarchy navigation

  • i18n (9 languages) and light/dark themes

  • HTMX-powered changelist partial updates

  • Sync PyMongo backend support

  • CSRF protection with session middleware

Configuration mapping

v0.x concept

v2 equivalent

Collection config dict

ModelAdmin class

Column definitions

list_display + @display

Custom formatters

@display methods

Search config

search_fields

Auth middleware

auth_dependency on mount_admin_app()

Need help?