docs: streamline release v2 documentation (#6760)
This commit is contained in:
1 parent
ac62e5bfd6
commit
b3aa6155cc
163 files changed
+2908
-4208
No files matched your search
@@ -4,120 +4,56 @@ sidebar_label: Overview
|
||||
tags: [Custom Widgets, API, JSX, MCP]
|
||||
---
|
||||
|
||||
import { BundledCustomWidgetGallery, CustomWidgetCodeExample } from "@site/src/components/custom-widget-code";
|
||||
|
||||
export const completeManifest = `{
|
||||
"$schema": "homarr-custom-widget-v2",
|
||||
"name": "Service status",
|
||||
"sources": {
|
||||
"default": { "name": "Service API", "baseUrl": "https://status.example.com", "networkScope": "public", "auth": "none" }
|
||||
},
|
||||
"requests": { "status": { "path": "/api/status" } },
|
||||
"options": {},
|
||||
"template": "<Badge color={data.status?.ok ? 'green' : 'red'}>{data.status?.label ?? 'Unknown'}</Badge>"
|
||||
}`;
|
||||
import { CustomWidgetFlowDiagram } from "@site/src/components/pages/core-concepts/technical-diagrams";
|
||||
|
||||
# Custom Widgets
|
||||
|
||||
:::warning Experimental feature
|
||||
|
||||
This feature is experimental and may change. Share feedback in the
|
||||
Custom Widgets may change during the v2 release cycle. Share feedback in the
|
||||
[Custom Widgets discussion](https://github.com/homarr-labs/homarr/discussions/categories/custom-widgets).
|
||||
|
||||
:::
|
||||
|
||||
Custom JSX v2 is Homarr's only Custom Widget format. A definition contains keyed API sources, keyed requests, optional widget options, and one safe JSX template. Credentials are encrypted separately and never exported.
|
||||
A **Custom Widget** is a validated `homarr-custom-widget-v2` definition containing API sources, queries and actions,
|
||||
optional settings, and a safe JSX template.
|
||||
|
||||
```ts
|
||||
interface HomarrCustomWidgetV2 {
|
||||
$schema: "homarr-custom-widget-v2";
|
||||
name: string;
|
||||
description?: string;
|
||||
iconUrl?: string;
|
||||
sources: Record<string, CustomWidgetSource>;
|
||||
requests: Record<string, CustomWidgetRequest>;
|
||||
options?: Record<string, CustomWidgetOption>;
|
||||
template: string;
|
||||
}
|
||||
```
|
||||
Homarr executes requests on the server and renders the template in a restricted runtime. Source credentials are
|
||||
encrypted separately and are not included in exports, prompts, browser data, or Workshop submissions.
|
||||
|
||||
### Design with AI
|
||||
<CustomWidgetFlowDiagram />
|
||||
|
||||
The **Design with AI** action is available while creating or editing a custom widget. Describe what the widget should show and,
|
||||
when [Assistant](../assistant) is enabled, send the request directly from the form. The generated prompt includes the
|
||||
widget schema and current non-secret configuration, but not the latest preview response. It proposes the matching create or
|
||||
update tool for your approval.
|
||||

|
||||
|
||||
Use the preview's **Data** tab to inspect the endpoint's real response shape and mention important fields in your request; the
|
||||
copied prompt does not automatically include the latest preview response. Saved secrets are never added to the prompt. **Copy to
|
||||
clipboard** remains available when the Assistant is disabled or when you prefer another AI service.
|
||||
## Manage Custom Widgets
|
||||
|
||||
<CustomWidgetCodeExample
|
||||
id="complete-widget-manifest"
|
||||
label="Complete manifest"
|
||||
code={completeManifest}
|
||||
height="360px"
|
||||
/>
|
||||
Administrators can create, import, duplicate, enable, export, publish, and delete definitions under
|
||||
**Management → Custom Widgets**. Adding or configuring one on a board also requires permission to modify that board.
|
||||
|
||||
The browser renders JSX. Homarr's server executes named requests, applies board permissions and network protections, and injects credentials. The browser never receives source credentials.
|
||||
Once placed, normal board permissions control rendering and requests. Queries can run for anonymous viewers on public
|
||||
boards; actions require authentication and the permission declared by the request.
|
||||
|
||||
## Permissions
|
||||
## Authoring
|
||||
|
||||
Custom Widget management is an administrator-only surface. Only a Homarr administrator can create, import, migrate,
|
||||
preview, publish, install, configure, or write secrets, including through HTTP authoring resources or MCP. An API key
|
||||
only lists Custom Widget MCP tools, prompts, and resources when its owner is an administrator.
|
||||
|
||||
Adding or configuring a Custom Widget placement requires both administrator access and permission to modify that
|
||||
board. Duplicating a board that contains Custom Widgets also requires an administrator. A non-administrator with
|
||||
board-modify access can move, resize, change presentation settings, or remove an existing placement, but cannot add one,
|
||||
change its definition, refresh interval, or Custom Widget options.
|
||||
|
||||
Once an administrator has placed a widget, ordinary board permissions apply to rendering and requests. Authorized
|
||||
non-administrators can use it on private boards, and queries can render for anonymous viewers on public boards.
|
||||
Mutations remain authenticated and enforce each request's view, modify, or full permission.
|
||||
|
||||
## Authoring paths
|
||||
|
||||
- [Create a Custom Widget](./authoring) visually or with one copied AI prompt.
|
||||
- [Use the JSX runtime](./custom-jsx) for data, Mantine components, temporary inputs, and diagnostics.
|
||||
- [Browse the supported component reference](./component-reference).
|
||||
- [Create a Custom Widget](./authoring) in the workbench or from a copied AI prompt.
|
||||
- [Use the safe JSX runtime](./custom-jsx) for data bindings, temporary inputs, and components.
|
||||
- [Browse the component reference](./component-reference).
|
||||
- [Configure requests and security](./requests-and-security).
|
||||
- [Use MCP and the skills.sh skill](./agent-authoring).
|
||||
- [Correct problems](./troubleshooting).
|
||||
- [Connect an agent](./agent-authoring) through MCP and the Homarr skill.
|
||||
- [Troubleshoot a definition](./troubleshooting).
|
||||
|
||||
The workbench provides visual source, request, and option editors, with raw JSON available for advanced use. Invalid
|
||||
values remain marked and disable preview and saving until corrected.
|
||||
|
||||
Exports, imports, Workshop, and MCP validate the same schema. Homarr also validates community content before
|
||||
installation.
|
||||
|
||||
Legacy definitions show a **Migration required** badge. Use **Copy migration prompt**, describe the visible layout
|
||||
without secrets, and import the returned v2 JSON with **Paste migrated widget**. Homarr preserves the v1 definition and
|
||||
encrypted secret for rollback; credentials never appear in prompts, logs, or exports.
|
||||
The workbench validates the same schema used by imports, Workshop, HTTP authoring resources, and MCP. Test every query
|
||||
and simulate relevant actions before saving. Live preview actions are opt-in because they can change the source service.
|
||||
|
||||
## Import and Workshop
|
||||
|
||||
Administrators can select **Import from Workshop** while adding a board item. Review the complete source and requested
|
||||
permissions, then confirm deployment-specific URLs and credentials. Private and loopback URLs must be confirmed or
|
||||
replaced for the current Homarr installation.
|
||||
Use **Import from Workshop** while adding board content or import a v2 JSON definition directly. Review the source,
|
||||
requested permissions, API hosts, and actions before installation, then configure deployment-specific URLs and
|
||||
credentials in Homarr.
|
||||
|
||||
Workshop publishes technically valid widgets immediately; users can vote or report them, and Workshop moderators can
|
||||
delete submissions. Community moderation is separate from Homarr administration and is not a security boundary. Review
|
||||
the source before installation and replace personal private-network hosts before publishing.
|
||||
Legacy definitions show **Migration required**. The migration prompt excludes credentials and the old display template;
|
||||
describe the visible behavior separately, import the returned v2 definition, and verify it before removing the archived
|
||||
version.
|
||||
|
||||
Connected agents can also search and install Workshop widgets. See [agent authoring](./agent-authoring) for the secure
|
||||
configuration flow; secret values are never returned through MCP.
|
||||
|
||||
## Reliability and rollback
|
||||
|
||||
Multiple Homarr replicas must use the same Redis service so Custom Widget response caches invalidate consistently.
|
||||
|
||||
Before upgrading, back up the database and `SECRET_ENCRYPTION_KEY`. A v1 rollback can read preserved v1 definitions,
|
||||
but widgets created only in v2 may be unavailable.
|
||||
|
||||
## Bundled examples
|
||||
|
||||
Homarr seeds five disabled examples without credentials and never overwrites an edited seed. They use the same public
|
||||
contract. Tautulli Activity is one of the bundled examples preserved from Homarr's AI authoring evaluation:
|
||||
|
||||
<BundledCustomWidgetGallery />
|
||||
Back up the database and `SECRET_ENCRYPTION_KEY` before upgrading or rolling back. Multi-replica installations must use
|
||||
the same Redis service so cached responses invalidate consistently.
|
||||
Reference in new issue
Block a user