feat: add django.core.checks for misconfiguration (#667)

New django_admin_react/checks.py registers a manage.py check validator with
actionable hints: django_admin_rest_api missing from INSTALLED_APPS (Error),
unimportable ADMIN_SITE dotted path (Error), unknown DJANGO_ADMIN_REACT keys
(Error, at startup vs a lazy ValueError), API_URL_PREFIX requiring the consumer
to mount the API (Warning), and a missing built bundle/Vite manifest (Warning).
Registered in AppConfig.ready(). Adds django_admin_rest_api to the test
project's INSTALLED_APPS (per its design) and a full-coverage test_checks.py.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: martin-castro-laminr-ai

django_admin_react/apps.py

@@ -6,6 +6,7 @@
 """
 
 from django.apps import AppConfig
+from django.core.checks import register
 
 
 class DjangoAdminReactConfig(AppConfig):
@@ -25,3 +26,15 @@ class DjangoAdminReactConfig(AppConfig):
     label = "django_admin_react"
     verbose_name = "Django Admin React"
     default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self) -> None:
+        """Register the package's system checks at app-load (#667).
+
+        Importing + registering here (not at module import time) keeps the
+        checks tied to the app registry being ready, matching Django's
+        documented pattern. The import is local so adding the app has no
+        eager import cost beyond the AppConfig itself.
+        """
+        from django_admin_react.checks import check_django_admin_react
+
+        register(check_django_admin_react)

django_admin_react/checks.py

@@ -0,0 +1,161 @@
+"""System checks for django_admin_react (#667).
+
+Registered against ``django.core.checks`` so common misconfigurations
+surface at ``manage.py check`` (and on every ``runserver`` boot) with an
+actionable hint — instead of a lazy ``ValueError`` on first settings
+access, a runtime 500, or a silent template fallback.
+
+What we validate:
+
+- ``django_admin_rest_api`` is installed (the package implements no API of
+  its own — every JSON endpoint lives in that sibling package).
+- ``DJANGO_ADMIN_REACT["ADMIN_SITE"]`` (dotted path) actually imports.
+- ``DJANGO_ADMIN_REACT`` has no unknown keys (the same guard ``conf._load``
+  enforces lazily — surfaced here at startup as a clean check error).
+- ``API_URL_PREFIX`` mounting is coherent: when it is set, the package
+  skips its inline ``api/v1/`` include, so the consumer must mount
+  ``django_admin_rest_api.urls`` themselves — a Warning reminds them.
+- The built SPA bundle / Vite manifest exists (a Warning, not an Error —
+  the package serves a friendly "not built" shell, and the manifest is
+  absent in a source checkout / before ``pnpm build``).
+
+Severities follow Django's convention: an ``Error`` blocks (the package
+cannot work); a ``Warning`` is a likely-misconfiguration heads-up that
+does not hard-block.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.core.checks import Error
+from django.core.checks import Warning as CheckWarning
+
+# Stable check IDs (Django convention ``<app_label>.E/W###``) so a consumer
+# can silence a specific one via ``SILENCED_SYSTEM_CHECKS`` if they must.
+ID_REST_API_MISSING = "django_admin_react.E001"
+ID_ADMIN_SITE_IMPORT = "django_admin_react.E002"
+ID_UNKNOWN_SETTINGS = "django_admin_react.E003"
+ID_API_PREFIX_MOUNT = "django_admin_react.W001"
+ID_BUNDLE_MISSING = "django_admin_react.W002"
+
+
+def check_django_admin_react(app_configs: Any, **kwargs: Any) -> list[Any]:
+    """Run every package configuration check.
+
+    Registered as a single callable (rather than many) so the import
+    surface stays small and the ordering is explicit. ``app_configs`` /
+    ``kwargs`` are the Django check-framework signature; unused here
+    because the checks are global to the package, not per-app.
+    """
+    errors: list[Any] = []
+    errors.extend(_check_rest_api_installed())
+    errors.extend(_check_admin_site_imports())
+    errors.extend(_check_settings_keys())
+    errors.extend(_check_api_prefix_coherence())
+    errors.extend(_check_bundle_built())
+    return errors
+
+
+def _check_rest_api_installed() -> list[Any]:
+    from django.apps import apps as django_apps
+
+    if django_apps.is_installed("django_admin_rest_api"):
+        return []
+    return [
+        Error(
+            "'django_admin_rest_api' is not in INSTALLED_APPS.",
+            hint=(
+                "django-admin-react is a React SPA over django-admin-rest-api "
+                "and implements no API of its own. Add 'django_admin_rest_api' "
+                "to INSTALLED_APPS (it ships as a dependency)."
+            ),
+            id=ID_REST_API_MISSING,
+        )
+    ]
+
+
+def _check_admin_site_imports() -> list[Any]:
+    from django.utils.module_loading import import_string
+
+    from django_admin_react import conf as dar_conf
+
+    dotted = dar_conf.ADMIN_SITE
+    try:
+        import_string(dotted)
+    except ImportError as exc:
+        return [
+            Error(
+                f"DJANGO_ADMIN_REACT['ADMIN_SITE'] = {dotted!r} could not be imported " f"({exc}).",
+                hint=(
+                    "Point ADMIN_SITE at the dotted path of your AdminSite "
+                    "instance (e.g. 'myproject.admin.site' or the default "
+                    "'django.contrib.admin.site')."
+                ),
+                id=ID_ADMIN_SITE_IMPORT,
+            )
+        ]
+    return []
+
+
+def _check_settings_keys() -> list[Any]:
+    from django.conf import settings as django_settings
+
+    from django_admin_react.conf import DEFAULTS
+
+    overrides = getattr(django_settings, "DJANGO_ADMIN_REACT", {}) or {}
+    unknown = sorted(set(overrides) - set(DEFAULTS))
+    if not unknown:
+        return []
+    return [
+        Error(
+            "Unknown DJANGO_ADMIN_REACT key(s): " + ", ".join(unknown) + ".",
+            hint=("Remove the typo'd key(s). Valid keys are: " + ", ".join(sorted(DEFAULTS)) + "."),
+            id=ID_UNKNOWN_SETTINGS,
+        )
+    ]
+
+
+def _check_api_prefix_coherence() -> list[Any]:
+    from django_admin_react import conf as dar_conf
+
+    prefix = dar_conf.API_URL_PREFIX
+    if prefix is None:
+        # Inline mount is active; the package mounts the API itself. Nothing
+        # the consumer must do.
+        return []
+    # The override is set, so `django_admin_react.urls` skips the inline
+    # `api/v1/` include — the consumer MUST mount the REST API themselves at
+    # that prefix or every SPA data call 404s.
+    return [
+        CheckWarning(
+            f"DJANGO_ADMIN_REACT['API_URL_PREFIX'] = {prefix!r} is set, so this "
+            "package does NOT mount the REST API inline.",
+            hint=(
+                "Mount the sibling API yourself at that prefix, e.g.\n"
+                f"    path({prefix!r}, include('django_admin_rest_api.api.urls'))\n"
+                "or unset API_URL_PREFIX to use the package's inline 'api/v1/' mount."
+            ),
+            id=ID_API_PREFIX_MOUNT,
+        )
+    ]
+
+
+def _check_bundle_built() -> list[Any]:
+    # Imported lazily so the check module has no import-time dependency on
+    # the view layer.
+    from django_admin_react.views import _MANIFEST_PATH
+
+    if _MANIFEST_PATH.is_file():
+        return []
+    return [
+        CheckWarning(
+            "The built SPA bundle / Vite manifest was not found at " f"{_MANIFEST_PATH}.",
+            hint=(
+                "Install the published wheel (which ships the built bundle), or "
+                "build the frontend from source with 'pnpm --dir frontend build'. "
+                "Until then the SPA shell renders a 'not built yet' page."
+            ),
+            id=ID_BUNDLE_MISSING,
+        )
+    ]

tests/test_checks.py

@@ -0,0 +1,117 @@
+"""System-check tests (#667).
+
+Exercise every branch of ``django_admin_react.checks`` — the happy path
+(no findings with the test project's correct config) and each failure
+mode via ``override_settings`` / monkeypatching, asserting the right
+check ID and that the message carries an actionable hint.
+"""
+
+from __future__ import annotations
+
+import pytest
+from django.test import override_settings
+
+from django_admin_react import checks as dar_checks
+
+
+def _ids(findings: list) -> set[str]:
+    return {f.id for f in findings}
+
+
+def test_all_checks_pass_with_the_test_project_config() -> None:
+    # The test project installs django_admin_rest_api, a valid ADMIN_SITE,
+    # no unknown keys, the inline API mount, and a built manifest is present
+    # in the package's static dir — so the only finding we tolerate is the
+    # bundle-missing warning when running from a source checkout.
+    findings = dar_checks.check_django_admin_react(None)
+    blocking = [f for f in findings if f.id != dar_checks.ID_BUNDLE_MISSING]
+    assert blocking == [], blocking
+
+
+@override_settings(DJANGO_ADMIN_REACT={"NOPE_TYPO": 1})
+def test_unknown_settings_key_is_an_error_with_hint() -> None:
+    findings = dar_checks._check_settings_keys()
+    assert _ids(findings) == {dar_checks.ID_UNKNOWN_SETTINGS}
+    assert "NOPE_TYPO" in findings[0].msg
+    assert findings[0].hint
+
+
+def test_bad_admin_site_dotted_path_is_an_error() -> None:
+    # ADMIN_SITE is read off the cached conf module; reload it under the
+    # override so the bad value takes effect.
+    import importlib
+
+    from django_admin_react import conf as dar_conf
+
+    with override_settings(DJANGO_ADMIN_REACT={"ADMIN_SITE": "does.not.exist.site"}):
+        importlib.reload(dar_conf)
+        try:
+            findings = dar_checks._check_admin_site_imports()
+        finally:
+            # Restore the cached conf for the rest of the suite.
+            importlib.reload(dar_conf)
+    assert _ids(findings) == {dar_checks.ID_ADMIN_SITE_IMPORT}
+    assert findings[0].hint
+
+
+def test_api_prefix_set_emits_a_mount_warning() -> None:
+    import importlib
+
+    from django_admin_react import conf as dar_conf
+
+    with override_settings(DJANGO_ADMIN_REACT={"API_URL_PREFIX": "/api/api/v1/"}):
+        importlib.reload(dar_conf)
+        try:
+            findings = dar_checks._check_api_prefix_coherence()
+        finally:
+            importlib.reload(dar_conf)
+    assert _ids(findings) == {dar_checks.ID_API_PREFIX_MOUNT}
+    assert "/api/api/v1/" in findings[0].msg
+    assert findings[0].hint
+
+
+def test_api_prefix_unset_emits_no_warning() -> None:
+    # Default test config leaves API_URL_PREFIX unset → inline mount → quiet.
+    assert dar_checks._check_api_prefix_coherence() == []
+
+
+def test_rest_api_missing_is_an_error(monkeypatch: pytest.MonkeyPatch) -> None:
+    from django.apps import apps as django_apps
+
+    real_is_installed = django_apps.is_installed
+
+    def fake_is_installed(label: str) -> bool:
+        if label == "django_admin_rest_api":
+            return False
+        return real_is_installed(label)
+
+    monkeypatch.setattr(django_apps, "is_installed", fake_is_installed)
+    findings = dar_checks._check_rest_api_installed()
+    assert _ids(findings) == {dar_checks.ID_REST_API_MISSING}
+    assert "INSTALLED_APPS" in findings[0].hint
+
+
+def test_bundle_missing_is_a_warning(monkeypatch: pytest.MonkeyPatch, tmp_path) -> None:
+    from django_admin_react import views
+
+    # Point the manifest path at a file that doesn't exist.
+    monkeypatch.setattr(views, "_MANIFEST_PATH", tmp_path / "missing-manifest.json")
+    findings = dar_checks._check_bundle_built()
+    assert _ids(findings) == {dar_checks.ID_BUNDLE_MISSING}
+    assert findings[0].hint
+
+
+def test_bundle_present_emits_no_warning(monkeypatch: pytest.MonkeyPatch, tmp_path) -> None:
+    from django_admin_react import views
+
+    manifest = tmp_path / "manifest.json"
+    manifest.write_text("{}", encoding="utf-8")
+    monkeypatch.setattr(views, "_MANIFEST_PATH", manifest)
+    assert dar_checks._check_bundle_built() == []
+
+
+def test_check_is_registered_with_django() -> None:
+    from django.core.checks import registry
+
+    registered = {c for c in registry.registry.get_checks()}
+    assert dar_checks.check_django_admin_react in registered

tests/test_project/settings.py

@@ -24,6 +24,9 @@
     # invisible on every legacy admin page). Documented in the
     # README's "Experience-toggle strip" section.
     "django_admin_react",
+    # The sibling REST API package — django_admin_react is a thin SPA layer
+    # over it, and the package's system check (#667) expects it installed.
+    "django_admin_rest_api",
     "django.contrib.admin",
     "django.contrib.auth",
     "django.contrib.contenttypes",