Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(sdk): a second widget surface — types users place, not just slots

Juan Denis92e0750262f1
diff --git a/backend/app/api/plugins.py b/backend/app/api/plugins.py
index 229246ba..7c6d6171 100644
--- a/backend/app/api/plugins.py
+++ b/backend/app/api/plugins.py
@@ -487,6 +487,8 @@ def get_manifest_spec():
'page_titles': {'type': 'object', 'description': 'Map of route path → document title.'},
'command_palette': {'type': 'array', 'description': '{label, path, category, keywords}.'},
'widgets': {'type': 'array', 'description': '{slot, component}. slot=global renders globally inside DashboardLayout.'},
+ 'dashboard_widgets': {'type': 'array',
+ 'description': 'Placeable dashboard widget types: {id, name, component, icon?, category?, description?, w?, h?, min?, default_cfg?}. Unlike widgets (fixed host slot), these appear in the dashboard widget library and the user positions, resizes and configures instances of them.'},
'layouts': {'type': 'array',
'description': 'Custom layout components: {id, component}. The component must render <Outlet/> somewhere; it wraps every route that references its id. Built-in layouts (padded, full, bare) are reserved.'},
},
diff --git a/backend/app/services/contribution_service.py b/backend/app/services/contribution_service.py
index a10a241d..8eec9d5a 100644
--- a/backend/app/services/contribution_service.py
+++ b/backend/app/services/contribution_service.py
@@ -9,10 +9,21 @@ A plugin manifest may declare a `contributions` block with any subset of:
"page_titles": { "/some-path": "Title" },
"command_palette":[{ label, path, category, keywords }],
"widgets": [{ slot, component }],
+ "dashboard_widgets": [{ id, name, component, icon?, category?,
+ description?, w?, h?, min?, default_cfg? }],
"layouts": [{ id, component }],
"tabs": [{ group, to, label, icon?, end?, order? }]
}
+`widgets` and `dashboard_widgets` are different surfaces and are easy to
+confuse. A `widgets` entry mounts a component at a FIXED host slot
+(`<PluginSlot name="dashboard.top" />`) — the host decides where it goes and
+the user cannot move it. A `dashboard_widgets` entry registers a placeable
+widget TYPE: it appears in the dashboard's widget library, and the user adds,
+positions, resizes and configures instances of it on a dashboard board. Use
+`widgets` to enrich an existing page, `dashboard_widgets` to offer a new
+building block.
+
A `tabs` entry adds a tab to a core-owned TabGroupLayout group; `group` is the
core group id (== the sidebar item id: files | servers | monitoring). Pair it
with a route contribution carrying the same `group` so the page renders INSIDE
@@ -99,6 +110,7 @@ def get_active_contributions():
page_titles = {}
command_palette = []
widgets = []
+ dashboard_widgets = []
layouts = []
tabs = []
# AI assistant contributions: per-route suggested prompts + custom
@@ -114,6 +126,7 @@ def get_active_contributions():
routes.extend(_tag(contrib.get('routes'), p.slug))
command_palette.extend(_tag(contrib.get('command_palette'), p.slug))
widgets.extend(_tag(contrib.get('widgets'), p.slug))
+ dashboard_widgets.extend(_tag(contrib.get('dashboard_widgets'), p.slug))
layouts.extend(_tag(contrib.get('layouts'), p.slug))
tabs.extend(_tag(contrib.get('tabs'), p.slug))
@@ -134,6 +147,7 @@ def get_active_contributions():
'page_titles': page_titles,
'command_palette': command_palette,
'widgets': widgets,
+ 'dashboard_widgets': dashboard_widgets,
'layouts': layouts,
'tabs': tabs,
'ai': ai,
diff --git a/backend/app/services/plugin_service.py b/backend/app/services/plugin_service.py
index 7a0ad587..23492468 100644
--- a/backend/app/services/plugin_service.py
+++ b/backend/app/services/plugin_service.py
@@ -343,6 +343,7 @@ _REQUIRED_CONTRIB_KEYS = {
'tabs': ('group', 'to', 'label'),
'command_palette': ('label', 'path'),
'widgets': ('slot', 'component'),
+ 'dashboard_widgets': ('id', 'name', 'component'),
'layouts': ('id', 'component'),
}
diff --git a/backend/app/utils/sdk.py b/backend/app/utils/sdk.py
index edd401fc..43c7b506 100644
--- a/backend/app/utils/sdk.py
+++ b/backend/app/utils/sdk.py
@@ -27,7 +27,7 @@ import re
from app.utils.version import compare_versions
# Keep in lock-step with frontend/src/plugins/sdk/index.js `SDK_VERSION`.
-SDK_VERSION = '1.0.0'
+SDK_VERSION = '1.1.0'
def _version_tuple(v):
diff --git a/backend/tests/test_plugins_pipeline.py b/backend/tests/test_plugins_pipeline.py
index dd5ddd75..2984c070 100644
--- a/backend/tests/test_plugins_pipeline.py
+++ b/backend/tests/test_plugins_pipeline.py
@@ -61,6 +61,12 @@ def _write_builtin(builtin_dir, slug='serverkit-demo', version='1.0.0',
# TabGroupLayout group, paired with the group route above.
'tabs': [{'group': 'files', 'to': '/demo-tab', 'label': 'Demo Tab',
'icon': '<circle cx="12" cy="12" r="8"/>'}],
+ # Placeable dashboard widget type (plan 62): shows up in the
+ # dashboard widget library, not at a fixed host slot.
+ 'dashboard_widgets': [{'id': 'demo-widget', 'name': 'Demo Widget',
+ 'component': 'DemoWidget', 'category': 'Utility',
+ 'w': 3, 'h': 2, 'min': [2, 2],
+ 'default_cfg': {'limit': 5}}],
},
}
(folder / 'plugin.json').write_text(json.dumps(manifest), encoding='utf-8')
@@ -188,7 +194,7 @@ def test_contributions_endpoint_envelope(app, client, auth_headers, plugin_dirs)
# The envelope always carries every key.
for key in ('nav', 'routes', 'page_titles', 'command_palette', 'widgets',
- 'layouts', 'tabs', 'ai'):
+ 'dashboard_widgets', 'layouts', 'tabs', 'ai'):
assert key in data
# Contributions are tagged with the source plugin slug.
@@ -205,6 +211,13 @@ def test_contributions_endpoint_envelope(app, client, auth_headers, plugin_dirs)
assert any(r.get('plugin') == 'serverkit-demo' and r.get('group') == 'files'
and r.get('component') == 'DemoTabPage' for r in data['routes'])
+ # Placeable dashboard widget types travel on their own key, tagged with the
+ # slug, and never leak into the fixed-slot `widgets` surface.
+ assert any(w.get('plugin') == 'serverkit-demo' and w.get('id') == 'demo-widget'
+ and w.get('component') == 'DemoWidget'
+ for w in data['dashboard_widgets'])
+ assert not any(w.get('id') == 'demo-widget' for w in data['widgets'])
+
def test_disabled_plugin_drops_from_contributions(app, client, auth_headers, plugin_dirs):
_write_builtin(plugin_dirs['builtin'])
diff --git a/docs/EXTENSIONS.md b/docs/EXTENSIONS.md
index a646f09f..b323d138 100644
--- a/docs/EXTENSIONS.md
+++ b/docs/EXTENSIONS.md
@@ -106,6 +106,11 @@ tagged at runtime with its source `plugin` slug so the frontend can resolve
{ "label": "Git", "path": "/git", "category": "Pages", "keywords": "repos deploy" }
],
"widgets": [ { "slot": "dashboard.top", "component": "GitStatusWidget" } ],
+ "dashboard_widgets": [
+ { "id": "git-activity", "name": "Git activity", "component": "GitActivityWidget",
+ "category": "Operations", "description": "Recent pushes across repositories",
+ "w": 4, "h": 3, "min": [3, 2], "default_cfg": { "limit": 6 } }
+ ],
"layouts": [ { "id": "my-fullscreen", "component": "MyLayout" } ],
"tabs": [
{ "group": "files", "to": "/ftp", "label": "FTP Server", "icon": "<rect …/>" }
@@ -123,7 +128,8 @@ tagged at runtime with its source `plugin` slug so the frontend can resolve
| `routes` | `{path,component,layout?,group?}` | `component` = a named export of the plugin's `index.{js,jsx}`. `layout`: `padded` (default) / `full` / `bare` / a custom layout id. `group` nests the route inside a core tab group instead — see [Tab-group contributions](#tab-group-contributions). |
| `page_titles` | `{ "/path": "Title" }` | Sets `document.title`. |
| `command_palette` | `{label,path,category,keywords}` | `category` defaults to `Extensions`. |
-| `widgets` | `{slot,component}` | Slots: `global` (renders inside DashboardLayout), plus the enrich-core slots (`dashboard.top`, `service.detail.tab`, `domain.drawer.panel`). |
+| `widgets` | `{slot,component}` | Slots: `global` (renders inside DashboardLayout), plus the enrich-core slots (`dashboard.top`, `service.detail.tab`, `domain.drawer.panel`). Fixed position — the host decides where it renders. |
+| `dashboard_widgets` | `{id,name,component,icon?,category?,description?,w?,h?,min?,default_cfg?}` | Registers a **placeable** widget type in the dashboard widget library. The user adds, moves, resizes and configures instances on their own boards. `category`: Metrics/Inventory/Operations/Utility (defaults to `Extensions`). `w`/`h` = default span in a 12-column grid; `min` = `[minW,minH]`. The component receives `{ widget, ctx }` — see [Dashboard widgets](#dashboard-widgets). |
| `layouts` | `{id,component}` | Custom wrappers; the component must render `<Outlet/>`. Built-in ids `padded`/`full`/`bare` are reserved. |
| `tabs` | `{group,to,label,icon?,end?,order?}` | Adds a tab to a core-owned tab group. `group` = the group id (`files` / `servers` / `monitoring`). See [Tab-group contributions](#tab-group-contributions). |
| `ai` | `{suggested_prompts,tool_renderers}` | See [AI](#extending-the-ai-assistant). |
@@ -136,6 +142,55 @@ tagged at runtime with its source `plugin` slug so the frontend can resolve
fullscreen authenticated pages.
- `<custom-id>` — wrapped in a `layouts`-contributed component.
+### Dashboard widgets
+
+The dashboard is a 12-column grid of user-placed widgets. `dashboard_widgets`
+registers a widget **type** so it appears in the widget library and users can
+drop instances onto their own boards.
+
+Don't confuse the two widget surfaces:
+
+| | `widgets` | `dashboard_widgets` |
+|---|---|---|
+| Where it renders | a fixed host slot you name | anywhere the user drags it |
+| Who decides position | the host | the user |
+| Instances | one per slot | many, each independently configured |
+| Use it to | enrich an existing page | offer a new building block |
+
+```jsonc
+"dashboard_widgets": [
+ { "id": "git-activity",
+ "name": "Git activity",
+ "component": "GitActivityWidget", // named export of your index module
+ "category": "Operations", // Metrics|Inventory|Operations|Utility
+ "description": "Recent pushes across repositories",
+ "w": 4, "h": 3, "min": [3, 2], // default span / minimum span
+ "default_cfg": { "limit": 6 } }
+]
+```
+
+Ids are namespaced by the panel as `<plugin-slug>:<id>`, so two extensions can
+both ship a `activity` widget without colliding.
+
+Your component receives two props:
+
+```jsx
+export function GitActivityWidget({ widget, ctx }) {
+ // widget.cfg — this instance's config, seeded from default_cfg
+ // widget.w / widget.h — its current span, if you want to adapt density
+ // ctx.range — '1h' | '6h' | '24h' | '7d' | '30d' (the board's time range)
+ // ctx.tick — increments on each refresh; put it in your effect deps
+ // ctx.serverVar — the board's selected server ('local' or a server id)
+ // ctx.isAdmin, ctx.navigate
+ return <div className="skw-list">…</div>;
+}
+```
+
+Render into the space you're given: the frame's header, menu and resize handle
+are the host's. A widget that throws is caught and replaced with an error tile
+rather than taking the board down, but handle your own loading and empty states
+— every core widget does.
+
### Tab-group contributions
Some core surfaces are **tab groups** (one shared `PageTopbar` + routed tabs,
diff --git a/frontend/src/plugins/contributions.js b/frontend/src/plugins/contributions.js
index ea8d8ac7..52e243b7 100644
--- a/frontend/src/plugins/contributions.js
+++ b/frontend/src/plugins/contributions.js
@@ -78,6 +78,13 @@ const EMPTY = {
page_titles: {},
command_palette: [],
widgets: [],
+ // Placeable dashboard widget TYPES: { id, name, component, icon?,
+ // category?, description?, w?, h?, min?, default_cfg? }. Distinct from
+ // `widgets` above, which mounts a component at a fixed host slot. These
+ // show up in the dashboard widget library and the user positions, sizes
+ // and configures instances of them. Consumed by
+ // components/dashboard/widgets/registry.js via useWidgetTypes().
+ dashboard_widgets: [],
layouts: [],
// Tabs contributed into core-owned TabGroupLayout groups (#43):
// { group, to, label, icon?, end?, order? }. `group` is the core group id
@@ -118,6 +125,7 @@ function getBuildTimeContributions() {
const page_titles = {};
const command_palette = [];
const widgets = [];
+ const dashboard_widgets = [];
const layouts = [];
const tabs = [];
const ai = { suggested_prompts: [], tool_renderers: [] };
@@ -134,6 +142,7 @@ function getBuildTimeContributions() {
routes.push(...tagItems(contrib.routes, slug));
command_palette.push(...tagItems(contrib.command_palette, slug));
widgets.push(...tagItems(contrib.widgets, slug));
+ dashboard_widgets.push(...tagItems(contrib.dashboard_widgets, slug));
layouts.push(...tagItems(contrib.layouts, slug));
tabs.push(...tagItems(contrib.tabs, slug));
@@ -153,6 +162,7 @@ function getBuildTimeContributions() {
page_titles,
command_palette,
widgets,
+ dashboard_widgets,
layouts,
tabs,
ai,
diff --git a/frontend/src/plugins/sdk/index.js b/frontend/src/plugins/sdk/index.js
index 39a31316..bf433e15 100644
--- a/frontend/src/plugins/sdk/index.js
+++ b/frontend/src/plugins/sdk/index.js
@@ -38,7 +38,7 @@
// GET /api/v1/plugins/contributions. The backend mirror lives in
// backend/app/utils/sdk.py — keep the two in lock-step (asserted by
// backend/tests/test_sdk_contract.py).
-export const SDK_VERSION = '1.0.0';
+export const SDK_VERSION = '1.1.0';
export { api, default as defaultApi } from '../../services/api';