Wagtail Developer Reference

A visual auditing tool for Wagtail developers. This package provides a live registry of your project's architecture, making it easy to track Page models and StreamField blocks across complex, multi-site setups.

Why use this?

In large Wagtail projects, it’s easy to lose track of where specific blocks are used or which templates are being rendered. This tool gives you a "God-view" of your components without needing to dig through the database or shell.

Features

• Fast registry: Code definitions are cached per worker; the normal registry response stays small and paginates at 20 rows.
• On-demand exact usage: PAGE and BLOCK counts are calculated only for a usage range, scoped to the exact page model, StreamField and nested definition path.
• Scalable StreamField inspection: Usage scans read raw StreamField JSON, avoiding chooser-object queries while keeping totals current.
• Searchable block picker: An accessible, collapsed picker searches all definitions server-side and returns at most 30 choices at once.
• Multi-site aware: Site root pages are included, nested subsites are excluded from parent-site counts, and an empty site filter aggregates globally.
• Usage inspection: Open an exact definition's paginated page list and copy the visible usage table in one click.
• Template discovery: See the template path associated with every component.

Installation

Compatibility: Python 3.9+ and Wagtail 4.1 through 7.4.2 LTS. Wagtail 7.4 itself requires Python 3.10+.

1. Add `wagtail_developer_reference` to your `INSTALLED_APPS`: ```python INSTALLED_APPS = [ ..., "wagtail_developer_reference", ] ```

2. Run migrations so Django creates the package permission:

   python manage.py migrate

3. Grant access in the Django admin:

   • Open a user or group in the Django admin.
   • Assign Wagtail developer reference | developer reference access | Can access the Wagtail developer reference.

4. Usage:

   • Login to the Wagtail Admin with an account that has that permission explicitly assigned.
   • Find the "System Registry" item in the sidebar menu.

By default, no account can see the menu item or access the URLs. Superusers are not granted access automatically by this package; assign the permission directly or through a group.

Settings

WAGTAIL_DEVELOPER_REFERENCE_ALLOW_ALL_ADMIN_USERS

Default: False.

Set this to True in your Django settings to allow all active, authenticated users with access to the Wagtail admin (wagtailadmin.access_admin) to see the System Registry menu item and access the Developer Reference URLs, without assigning the additional Developer Reference permission:

WAGTAIL_DEVELOPER_REFERENCE_ALLOW_ALL_ADMIN_USERS = True

This includes active superusers. When omitted or set to False, the explicit user or group permission described above is still required, including for superusers.

License

Internal Use Only - Copyright © 2026 Fourdigits. All rights reserved.