:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Dashboard widgets
Embeddable dashboard tiles backed by DashboardWidget and rendered through the product-local frontend registry in products/dashboards/frontend/.
In scope: widget tiles (widget_id on DashboardTile).
Out of scope: insight tiles, text cards, and button tiles — separate models today.
Reference implementations: products/dashboards/frontend/widgets/error_tracking/ (error_tracking_list), products/dashboards/frontend/widgets/session_replay/ (session_replay_list).
Architecture (sketch)
DashboardTile (layout) → widget_id → DashboardWidget (team-scoped)
widget_type + config → WIDGET_REGISTRY (BE) → run_widgets
→ DASHBOARD_WIDGET_CATALOG + registry.tsx (FE)
New widget_type strings need no migration — register backend + frontend + both catalogs.
Schema changes on DashboardWidget / DashboardTile use the dashboards migration chain — invoke django-migrations when touching those models.
Layer table, registry shapes, copy/move, analytics, and typing details: .agents/skills/manage-dashboard-widgets/references/architecture.md
Playbook
Canonical guide: .agents/skills/manage-dashboard-widgets/ (/manage-dashboard-widgets — ship new types or update shipped types; intake only for new types).
| Task | Doc |
|---|---|
| Add a new widget type | SKILL.md §2 Ship → intake, then checklist |
| First widget in a new product area | Same — checklist §4c |
| Update an existing widget type | SKILL.md §3 Update → managing-existing-widgets |
| Live / self-updating widget | references/live-widgets.md → frontend/widgets/live/ toolkit |
| Tile min/max size on dashboard grid | references/layout-and-ux.md (§ Tile min/max size) |
| WidgetCard, loading, headers | references/composition.md |
| RBAC, copy/move, shared dashboards | references/permissions-and-sharing.md |
| Architecture, naming, scaling rules | references/architecture.md |
| MCP / REST | references/mcp.md |
| Keep skill docs in sync | references/skill-maintenance.md |
Critical rules:
- Product RBAC is registry-driven — see permissions-and-sharing.md § Product RBAC.
- Charts/trends on a dashboard → insight tiles, not new widget types — architecture.md § Charts.
Frontend / backend parity
Config shape has one SSOT; UI metadata stays hand-written.
| Layer | Location | Hand-written? |
|---|---|---|
| Config contract (Pydantic) | backend/widget_specs/configs.py |
Yes — edit first |
| Runtime validation | backend/widget_specs/registry.py (validate_widget_config) |
Derived |
| Registry manifest | backend/widget_specs/registry.py → EXPECTED_WIDGET_TYPES |
Per-type WidgetSpec entry |
| Agent catalog | backend/widget_catalog.py (derived from WIDGET_SPECS) |
Labels in registry.py; config_schema = model_json_schema() |
| OpenAPI config | backend/widget_specs/openapi.py |
Stub DRF serializers + Pydantic model_json_schema() via pydantic_openapi.py postprocessing |
| FE config Zod | frontend/generated/widget-configs.zod.ts + widget-config-schemas/ |
Codegen — hogli build:widget-types (Orval generateReusableSchemas) |
| FE config property keys | frontend/generated/widget-config-property-keys.json |
Codegen — generate-widget-config-zod.mjs (parity tests) |
| Widget date presets | frontend/generated/widget-date-from-options.json |
Codegen — build-dashboard-widget-types.py (constants.py values + labels) |
| Widget form field picks | frontend/generated/widget-form-fields.json |
Codegen — WidgetSpec.form_fields in registry.py |
| FE UI catalog | frontend/widget_types/catalog.ts |
Yes — layouts, copy |
| FE previews | frontend/widgets/previews/dashboardWidgetPreviews.ts |
Yes — preview component per widget type (kept out of the catalog so the app shell stays small) |
| FE runtime registry | frontend/widgets/registry.tsx |
Yes — Component, EditModal |
Per-type add flow (ordered): checklist-new-widget-type.md. Platform invariants: architecture.md.
Verify
Full command list: .agents/skills/manage-dashboard-widgets/SKILL.md § Verify.
Minimum when adding a type:
hogli test products/dashboards/backend/api/test/test_run_widgets.py
hogli test products/dashboards/backend/api/test/test_dashboard_widgets.py
hogli test products/dashboards/frontend/widgets/registry.test.tsx
After widget_specs/ changes: hogli build:openapi (OpenAPI serializers derive automatically; do not edit products/dashboards/frontend/generated/).