Cette page n’est pas encore disponible en Français ; elle s’affiche donc en anglais.
Dashboard widgets from a plugin
Declare a widget in module.json, render plain data in register(), and let the dashboard draw, validate and sanitise it.
A plugin widget joins the dashboard catalogue as plugin:<pluginId>:<widgetId> and takes part in Customise (show / hide / order / size), the shared default layout and the “New” badges exactly like built-in widgets. It is shown only while the plugin is enabled and the user holds one of its perms.
"widgets": [
{
"id": "upcoming",
"title": "Upcoming site visits",
"description": "The next planned site visits with customer and day.",
"group": "Operations",
"size": "sm",
"perm": ["sitevisits.view"],
"visible": true
}
]Rules: id matches ^[a-z][\w-]{0,40}$ and is unique in the plugin; description has at least 12 characters; group is one of Overview, Sales, Money, Operations, People, Website, System (default System); size is sm, md or lg (default sm); at most 12 widgets per plugin.
widgets: {
// ctx = { pluginId, log, userId, may, now, size }
upcoming: async (ctx) => {
const rows = await prisma.siteVisit.findMany({ where: { status: "PLANNED", plannedAt: { gte: ctx.now } }, orderBy: { plannedAt: "asc" }, take: 5 });
return {
kind: "list",
href: "/admin/site-visits",
linkLabel: "All visits",
empty: "No visits planned.",
items: rows.map((r) => ({ title: r.customerName, subtitle: r.slot, meta: r.plannedAt.toISOString().slice(0, 10), href: "/admin/site-visits?id=" + r.id })),
};
},
},src/components/admin/dashboard/widgets/plugin.tsx), validates it with zod and shows links only when the user may open them. Each widget streams in its own Suspense boundary, so a slow widget delays only itself — but keep the query cheap: it runs on every dashboard load.Written from: docs/PLUGIN-DEVELOPER-GUIDE.md, src/lib/plugins/types.ts, src/lib/plugins/widgets.ts, src/components/admin/dashboard/widgets/plugin.tsx