docs: streamline release v2 documentation (#6760)
This commit is contained in:
Thomas authored and 
GitHub committed
1 parent
ac62e5bfd6
commit
b3aa6155cc
163 files changed
+2908
-4208
No files matched your search
@@ -1,153 +1,45 @@
|
||||
# Use agents and skills.sh
|
||||
# Connect an agent
|
||||
|
||||
An external agent can create one widget or a coordinated set with the Homarr MCP server. For a set, it researches a
|
||||
service once, divides distinct user jobs into useful widgets, and validates every definition independently.
|
||||
An MCP-connected agent can validate, preview, test, and save Custom Widgets. The API key owner must be a Homarr
|
||||
administrator.
|
||||
|
||||
For example, a request for a Seerr widget can become a coordinated library/request-status widget and an interactive
|
||||
media-search widget that submits requests, when the service's documented API and the user's permissions support those
|
||||
flows.
|
||||
|
||||
The MCP API key must belong to a Homarr administrator. Non-administrator keys do not list Custom Widget tools, prompts,
|
||||
or resources. The same administrator requirement applies to the matching HTTP authoring endpoints.
|
||||
|
||||
<a className="button button--primary" href="https://www.skills.sh/homarr-labs/homarr/homarr-custom-widget">
|
||||
View the Custom Widget Skill on skills.sh
|
||||
</a>
|
||||
|
||||
Install the Agent Skill from the verified Homarr repository:
|
||||
Install the official skill:
|
||||
|
||||
```sh
|
||||
npx skills add https://github.com/homarr-labs/homarr --skill homarr-custom-widget
|
||||
```
|
||||
|
||||
The portable skill gives concise authoring guidance. For connected agents, Homarr returns a compact `SKILL.md` and a
|
||||
reference index. The agent loads only the named schema, runtime, or security reference and component documentation the
|
||||
current design needs.
|
||||
The skill routes the agent to the release-matched schema, runtime, security, examples, and component metadata. It keeps
|
||||
those references separate so the agent loads only what the current widget needs.
|
||||
|
||||
The workbench's **Copy AI prompt** action is separate. It creates a self-contained prompt below 12,000 characters for an ordinary ChatGPT or Claude conversation. It includes the lean contract, bindings, recommended components, and two polished examples. It never tells an offline model to call MCP tools.
|
||||
|
||||
The source is in [`.agents/skills/homarr-custom-widget`](https://github.com/homarr-labs/homarr/tree/HEAD/.agents/skills/homarr-custom-widget). `HEAD` follows the repository default branch, so the link is not tied to an unreleased feature branch. Homarr does not provide a ZIP archive.
|
||||
|
||||
After publication, run the installation command once. This action registers installation activity.
|
||||
|
||||
Then, verify the skills.sh page. Request official maker attribution for `homarr-labs` from skills.sh.
|
||||
|
||||
Repository code cannot give this attribution.
|
||||
|
||||
## Get MCP resources
|
||||
## MCP resources
|
||||
|
||||
- Prompt: `homarr-custom-widget-author`
|
||||
- Resources: `homarr://custom-widgets/schema`, `components`, `components/{name}`, `examples/{name}`, `skill`, and
|
||||
`references/{schema|runtime|security}`
|
||||
- HTTP: `GET /api/custom-widgets/authoring-prompt`, `schema`, `components`, `skill`, and
|
||||
`reference-{schema|runtime|security}`
|
||||
- Skill: `homarr://custom-widgets/skill`
|
||||
- References: `homarr://custom-widgets/references/{schema|runtime|security}`
|
||||
- Schema: `homarr://custom-widgets/schema`
|
||||
- Components: `homarr://custom-widgets/components` and `components/{name}`
|
||||
- Examples: `homarr://custom-widgets/examples/{name}`
|
||||
|
||||
The authoring-prompt tool description contains one sentence. The prompt contains the workflow instructions and resource links.
|
||||
Equivalent HTTP resources are available under `/api/custom-widgets/` for authenticated administrators.
|
||||
|
||||
`GET /api/custom-widgets/skill` and `customWidget_getSkill` return a compact structured skill payload:
|
||||
## Authoring lifecycle
|
||||
|
||||
```ts
|
||||
{
|
||||
name: "homarr-custom-widget";
|
||||
version: string;
|
||||
skillMd: string;
|
||||
references: Array<{
|
||||
name: "schema" | "runtime" | "security";
|
||||
tool: "customWidget_getReference";
|
||||
toolInput: { name: string };
|
||||
resource: string;
|
||||
httpResource: string;
|
||||
}>;
|
||||
skillsShUrl: string;
|
||||
sourceUrl: string;
|
||||
installCommand: string;
|
||||
}
|
||||
```
|
||||
1. Load the skill and only the references needed for the design.
|
||||
2. Read the external API documentation and build the definition.
|
||||
3. Validate the JSX, then create a preview from the complete definition.
|
||||
4. Run every returned query and simulate every relevant action against the current preview revision.
|
||||
5. Inspect the preview and redacted journal. Revise the existing preview for JSX-only changes.
|
||||
6. Save from the final tested preview.
|
||||
7. Configure deployment-specific source URLs and credentials, then preview the saved definition again.
|
||||
|
||||
The `homarr://custom-widgets/skill` MCP resource returns only the entrypoint Markdown. Named references remain separate
|
||||
so clients do not pay for unrelated material.
|
||||
Use `templateLines` for multiline JSX tool input. A preview must have current evidence for every query and action before
|
||||
it can be saved. Simulation counts as action evidence without performing the mutation.
|
||||
|
||||
The component catalog is a compact index of names, categories, safety levels, shared prop names, policies, and example
|
||||
IDs. Per-component results contain only component-specific props and a reference to shared prop documentation. Use
|
||||
`customWidget_getSharedProps` once with only the shared prop names needed across the selected components. This avoids
|
||||
repeating hundreds of global props in every tool result. The catalog and detailed references are deliberately not
|
||||
embedded in the skill or clipboard prompt.
|
||||
If the agent does not have a source URL or credential, it can request a short-lived Homarr configuration URL. An
|
||||
authenticated administrator completes it in Homarr; the agent receives the status, never the plaintext credential.
|
||||
|
||||
These interfaces do not return an archive URL or archive hash.
|
||||
Agents can also search, inspect, install, and configure existing Workshop widgets instead of regenerating them.
|
||||
|
||||
## Create a Custom Widget with MCP
|
||||
|
||||
Independent read-only discovery and reference calls can run together. Validation, preview, evidence, revision, and
|
||||
persistence calls run alone because each changes the active authoring phase.
|
||||
|
||||
1. Load `customWidget_getSkill`. Use its routing index to fetch only applicable named references with
|
||||
`customWidget_getReference`.
|
||||
2. For a new manifest, load the compact `schema` reference once; skip it when repairing a supplied valid v2 draft.
|
||||
Load the heavyweight live schema only when its extra detail is needed. Prefer `customWidget_findComponents` for a focused release-matched
|
||||
subset and reserve the full catalog for broad exploration, followed by `customWidget_getComponent` for only relevant
|
||||
installed components and `customWidget_getExample` when one example matches the interaction pattern. Fetch whatever
|
||||
named documentation the intended design requires without walking the whole catalog. If shared props are needed,
|
||||
collect their catalog names and call `customWidget_getSharedProps` once for that set.
|
||||
3. Read the external API documentation.
|
||||
4. Build each definition, using `templateLines` for multiline JSX tool input. Call `customWidget_validateTemplate`
|
||||
while drafting to repair JSX without resending the complete manifest. A valid template with an unknown-prop warning
|
||||
keeps one concrete `customWidget_getComponent` repair lookup active; otherwise proceed directly to preview. Homarr
|
||||
Assistant exposes only `templateLines` for validation and revision to prevent duplicate JSX tokens; direct MCP clients
|
||||
may send exactly one of `template` or `templateLines`.
|
||||
5. Send the coherent complete definition once to `customWidget_previewCreate`. It performs full validation and creates
|
||||
the preview session.
|
||||
6. Run `customWidget_previewQuery` for every query returned by the preview and inspect its actual status and data shape. Assistant conversations retain a bounded response preview so large APIs cannot exhaust the model context. Use
|
||||
`{}` for load queries; manual queries require exactly the returned primitive `parameterNames`.
|
||||
7. Test every relevant action returned by the preview in simulation mode. Verify its method, parameters, minimum board
|
||||
permission, confirmation, and invalidated queries before persistence.
|
||||
8. Open the returned preview path with browser tools.
|
||||
9. Inspect the redacted journal. For a JSX-only correction, validate the replacement template, then call
|
||||
`customWidget_previewReviseTemplate` with the session ID. Direct MCP clients may also pass the returned current revision
|
||||
for optimistic concurrency. It inherits sources, requests, options, and secrets without resending them, increments the
|
||||
revision, and returns fresh evidence lists. Use a new
|
||||
`customWidget_previewCreate` session only when sources, requests, or options change.
|
||||
10. Retest every returned query and action for the current revision. Earlier evidence remains in the journal but cannot
|
||||
satisfy persistence.
|
||||
11. Create the widget from that final tested preview with `customWidget_createFromPreview`. The preview session already carries
|
||||
the source URLs and encrypted credentials supplied during preview; the create call accepts only its session ID plus an
|
||||
optional target board and persists that tested preview only after every query and action has current evidence.
|
||||
12. Open its returned management path, and use a structured question when the user must choose whether to place it on a board.
|
||||
13. Otherwise, ask the user to configure the saved definition with the ten-minute Homarr source-setup URL.
|
||||
14. Create a final preview with the saved definition ID so Homarr loads its stored credentials, then test it again.
|
||||
15. Update the saved definition if the final verification finds a problem. `customWidget_update` also accepts
|
||||
`templateLines` for multiline JSX without resetting omitted options.
|
||||
16. Repeat the independent preview and persistence lifecycle for every widget in the requested set.
|
||||
|
||||
Template validation returns focused diagnostics. Preview creation and template revision return session metadata plus
|
||||
query/action checklists without echoing the definition. Keep the candidate locally and reuse the preview session for
|
||||
persistence.
|
||||
|
||||
For numeric API enums, prefer a guarded indexed literal label array in JSX over repeating a long ternary chain. The
|
||||
interpreter validates this pattern independently, and it keeps generated templates and repair calls substantially
|
||||
smaller while still rendering readable statuses.
|
||||
|
||||
A manual `SubFetch` returns to its trigger immediately when its request ID, parameters, or effective definition
|
||||
changes. Homarr hides the earlier result and does not fetch the new parameters until the user triggers it again, so
|
||||
bound search and pagination edits cannot silently relabel stale results.
|
||||
|
||||
Dependent bound controls can reset declaratively: `<Pagination bind="page" defaultValue={1} resetKey={inputs.search} />`
|
||||
returns to page 1 whenever the scalar search value changes. The reset remains local and does not execute a request.
|
||||
|
||||
After a successful manual query, a result-local `<RefreshButton requestId="search" label="Run again" />` reruns that
|
||||
query with unchanged parameters without adding another request definition or raw event handler.
|
||||
|
||||
Each source-configuration URL applies to one definition or preview and one source. It is short-lived, single-use, and
|
||||
can only be opened and completed by an authenticated Homarr administrator. The administrator confirms the server URL,
|
||||
network scope, and required credential fields directly in Homarr. The agent receives only request status and never
|
||||
receives plaintext credentials. Preview-scoped values expire with that preview; definition-scoped values persist.
|
||||
|
||||
Agents can install existing widgets without regenerating them:
|
||||
|
||||
1. Search with `customWidget_workshopSearch`.
|
||||
2. Inspect and validate a result with `customWidget_workshopGet`.
|
||||
3. Install it with `customWidget_workshopInstall`.
|
||||
4. Configure deployment-specific URLs and supplied credentials with `customWidget_sourceConfigure`.
|
||||
5. If the agent does not have those values, call `customWidget_configurationRequestUser` and wait for completion.
|
||||
6. Test the installed definition, then use `board_addItem` with kind `customApi` and the returned definition ID.
|
||||
|
||||
Homarr encrypts the plaintext immediately. Homarr does not return the plaintext.
|
||||
See [MCP](/docs/management/mcp) for client configuration and [requests and security](./requests-and-security) for the
|
||||
runtime limits.
|
||||
@@ -1,74 +1,29 @@
|
||||
# Create a Custom Widget
|
||||
|
||||
import { CanonicalCustomWidgetExample } from "@site/src/components/custom-widget-code";
|
||||
import workbenchImage from "./img/workbench.png";
|
||||
import workbenchMobileImage from "./img/workbench-mobile.png";
|
||||
import workbenchValidationImage from "./img/workbench-validation.png";
|
||||
The workbench provides editors for general metadata, API sources, requests, widget options, JSX, and preview data. Raw
|
||||
JSON is available when direct editing is faster.
|
||||
|
||||
The workbench exposes **General**, **API sources**, **Requests**, **Options**, **JSX**, and **Preview** sections. Advanced JSON is
|
||||
available in the manifest and request/option editors. Code and preview sit side by side on desktop; on smaller screens the
|
||||
**Configure**/**Preview** switch shows one pane at a time and the section navigation scrolls horizontally. Preview sizes display
|
||||
as **S/M/L** (Compact/Standard/Wide), and fixtures are **Live**, **Loading**, **Empty**, or **Error**.
|
||||
For multiline JSX, prefer `templateLines` in agent or MCP input and keep the final tested preview as the source of truth before saving.
|
||||
## Workflow
|
||||
|
||||
<img
|
||||
src={workbenchImage}
|
||||
alt="Custom Widget workbench with configuration sections and a live preview"
|
||||
style={{ maxWidth: "100%" }}
|
||||
/>
|
||||
1. Configure each API source, network scope, authentication method, and credential.
|
||||
2. Add named queries and actions. Values can reference widget options or invocation parameters.
|
||||
3. Define widget options and their defaults.
|
||||
4. Write JSX using `data`, `status`, `options`, and temporary `inputs`.
|
||||
5. Run **Test and preview**, inspect the response data and redacted request journal, then save.
|
||||
|
||||
<img
|
||||
src={workbenchMobileImage}
|
||||
alt="Mobile Custom Widget workbench with Configure and Preview switch and horizontally scrollable section navigation"
|
||||
style={{ maxWidth: "100%" }}
|
||||
/>
|
||||
Changing the definition, options, or credentials invalidates the previous preview. Preview actions are simulated unless
|
||||
**Run actions against the configured API** is enabled for that preview session.
|
||||
|
||||
The workbench keeps the configuration and preview together so you can inspect validation diagnostics, the redacted request
|
||||
journal, fixture data, and preview size before saving. Invalid fields stay marked in the form while the preview explains why it
|
||||
needs attention.
|
||||
Widget options support text, textarea, number, switch, select, multi-select, slider, date, time, color, icon, URL,
|
||||
duration, time zone, and JSON controls. Dynamic choices can come from a load query.
|
||||
|
||||
<img
|
||||
src={workbenchValidationImage}
|
||||
alt="Custom Widget workbench showing a Base URL validation error with Test, preview, and Create actions disabled"
|
||||
style={{ maxWidth: "100%" }}
|
||||
/>
|
||||
See the [safe JSX runtime](./custom-jsx), [component reference](./component-reference), and
|
||||
[request reference](./requests-and-security) for the authoring contract.
|
||||
|
||||
## Manual workflow
|
||||
## Create with another AI service
|
||||
|
||||
1. Configure the default API source, network scope, authentication, and credential.
|
||||
2. Add query/action cards. Values can be literals, widget options, or invocation parameters.
|
||||
3. Add widget options with their control and default value.
|
||||
4. Write responsive JSX using `data`, `status`, `options`, and temporary `inputs`.
|
||||
5. Test and preview, inspect Data and the redacted request journal, then save.
|
||||
**Create or fix with any AI** copies a self-contained prompt for an ordinary ChatGPT or Claude conversation. The model
|
||||
must return one fenced `json` block containing the complete definition. Paste that block into the workbench, add
|
||||
credentials separately, and validate it against a real preview.
|
||||
|
||||
While focus is inside a code editor, use `Ctrl+Z`/`Cmd+Z` to undo and `Ctrl+Shift+Z`/`Cmd+Shift+Z` to redo. The toolbar exposes the same actions. This history is local to that editor; builder-wide undo is not yet available.
|
||||
|
||||
Changing the definition, instance options, or credentials invalidates the previous preview and its live-action session. Run **Test and preview** again before treating the data or result as current. Automatic load queries are queued with up to four running at once so larger previews stay within the request limit.
|
||||
|
||||
<CanonicalCustomWidgetExample
|
||||
id="named-widget-requests"
|
||||
label="Named queries and actions"
|
||||
example="requests"
|
||||
height="420px"
|
||||
/>
|
||||
|
||||
<CanonicalCustomWidgetExample id="widget-options" label="Widget options" example="options" height="360px" />
|
||||
|
||||
Every option has a default. Supported controls include text, textarea, number, switch, select, multi-select, slider, date, time, color, icon, URL, duration, time zone, and JSON. Dynamic choices use `choicesFrom: { request, itemsPath?, valuePath, labelPath }`; the request must be a load query without invocation parameters, and you cannot provide both static `choices` and `choicesFrom`.
|
||||
|
||||
Preview actions are simulated by default and recorded in the journal without contacting the service. Enable **Run actions against the configured API** only when you intend a real mutation; live actions still require configured confirmation.
|
||||
|
||||
## ChatGPT or Claude
|
||||
|
||||
Open **Create or fix with any AI**, enter the desired widget and optional API documentation URL, then select the copy action beside the accordion title. The single self-contained prompt is below 12,000 characters, starts with your request, includes the lean contract and two polished examples, and never claims that an offline chat has MCP tools.
|
||||
|
||||
The model must return one fenced `json` block containing the complete widget, including the JSX in its `template`
|
||||
field. Copy that single block and select **Paste**. Homarr fills the visual builders and the JSX editor
|
||||
without any placeholder replacement or second paste.
|
||||
|
||||
Homarr shows all actionable schema or JSX errors inline. Enter credentials separately. The copied prompt does not include the
|
||||
latest preview response; use **Preview** > **Data** to inspect it and mention important response fields in your request. The prompt deliberately
|
||||
recommends a focused Mantine component set, visual hierarchy, responsive layout, theme compatibility, and loading,
|
||||
empty, failure, and success states.
|
||||
|
||||
Connected agents should use the skills.sh skill and retrieve the live schema and individual component metadata only as needed.
|
||||
For an MCP-connected agent, use the [Homarr Custom Widget skill](./agent-authoring) instead.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 58 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 78 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 90 KiB |
@@ -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.
|
||||
@@ -1,84 +1,52 @@
|
||||
# Correct Custom Widget problems
|
||||
# Custom Widget troubleshooting
|
||||
|
||||
## Correct an unavailable widget
|
||||
## Definition problems
|
||||
|
||||
The definition does not exist. If it was deleted, remove the unavailable tile from the board.
|
||||
| Symptom | Resolution |
|
||||
| ------------------------ | ---------------------------------------------------------------------------------------------------------- |
|
||||
| Definition unavailable | Restore or recreate the definition, or remove the unavailable board item. |
|
||||
| **Migration required** | Copy the migration prompt, describe the visible behavior without secrets, and import the returned v2 JSON. |
|
||||
| Invalid saved definition | Read the displayed schema errors, then recreate or import a valid definition. |
|
||||
| Invalid item options | Open the board item's settings and correct values that no longer match the definition. |
|
||||
|
||||
If the Custom Widgets page shows the definition with a **Migration required** badge, an administrator can open its
|
||||
action menu and select **Copy migration prompt**. Give that redacted prompt to an LLM, then import the resulting v2 JSON
|
||||
from the same menu. The LLM returns one complete JSON block; copy it once and select **Paste migrated widget**. Homarr
|
||||
places its `template` value into the JSX editor automatically. Because arbitrary v1 display text or JSX may contain
|
||||
credentials, the prompt omits that display configuration; describe the old widget's visible layout and behavior without
|
||||
including secrets. Other viewers see **Contact an administrator** instead of a migration link.
|
||||
Migrating a v1 definition keeps the archived v1 record and encrypted secret for rollback. The migrated v2 definition
|
||||
uses the same ID and takes precedence.
|
||||
|
||||
Homarr keeps the v1 definition and encrypted secret after migration. The validated v2 replacement uses the same ID and
|
||||
takes precedence; the archived v1 record reappears if the v2 replacement is deleted. There is no v1 permanent-delete
|
||||
action during the v2 stabilization period.
|
||||
## Validation errors
|
||||
|
||||
Otherwise, install or create a Custom JSX v2 definition.
|
||||
Start with the first diagnostic and its field path. Common causes are:
|
||||
|
||||
## Correct an invalid saved definition
|
||||
- invalid or duplicate source, request, or option IDs;
|
||||
- a request referencing a missing source;
|
||||
- an option default that does not match its control;
|
||||
- `{param:name}` in a load query;
|
||||
- missing invocation parameters;
|
||||
- an invalid source or icon URL;
|
||||
- a runtime component using the wrong request kind.
|
||||
|
||||
The Custom Widgets page isolates a definition that does not conform to the current schema. The other definitions remain available.
|
||||
The Diagnostics tab also shows JSX errors, accessibility checks, and the redacted request journal.
|
||||
|
||||
An invalid definition shows its validation errors. You can delete it.
|
||||
## Request errors
|
||||
|
||||
You cannot edit, enable, export, duplicate, publish, or select an invalid v2 definition. Recreate the definition or import a valid definition. Preserved v1 definitions use the separate **Migration required** workflow described above.
|
||||
Check the source URL, network scope, authentication, request method, path, body bindings, and board permission. The
|
||||
journal records the request ID, method, path template, status, and duration without credentials.
|
||||
|
||||
## Correct validation errors
|
||||
For `invalid placeholder`, use `{option:name}` or `{param:name}`. Load queries can reference options only.
|
||||
|
||||
Read the first schema or JSX diagnostic. Use its path to find the invalid value.
|
||||
In multi-replica deployments, connect every Homarr replica to the same Redis database. Otherwise an action can leave a
|
||||
stale cached query on another replica.
|
||||
|
||||
Make sure keyed API source and request names are valid and unique.
|
||||
## Runtime warnings
|
||||
|
||||
Make sure that each named request references an API source. Use explicit `$option` and `$param` references.
|
||||
|
||||
Make sure every option default matches its control. Use the correct request kind for each runtime component.
|
||||
|
||||
An incomplete API source URL or icon URL causes a form validation error. The workbench keeps the draft open.
|
||||
|
||||
The workbench marks the invalid field while you type. An invalid URL does not replace the form with the error boundary.
|
||||
|
||||
An invalid definition disables widget preview and Save/Create. The Data, Options, Actions, and Diagnostics tabs remain available so you can correct it.
|
||||
|
||||
The Diagnostics tab shows current schema and JSX errors, accessibility checks, and (after a preview) the redacted request
|
||||
journal. It does not expose credentials or raw secret values.
|
||||
`UNKNOWN_MANTINE_PROP` means the installed Mantine component does not document that property. Check the
|
||||
[component reference](./component-reference). `BLOCKED_CAPABILITY` means the runtime rejected an unsafe component,
|
||||
property, URL, or style capability.
|
||||
|
||||
## Workshop unavailable
|
||||
|
||||
If Workshop is unavailable, check `WORKSHOP_API_URL` and PocketBase health. Widgets that are already installed continue
|
||||
to work.
|
||||
Check `WORKSHOP_API_URL` and PocketBase health. Installed widgets continue to run without Workshop.
|
||||
|
||||
## Correct request errors
|
||||
## Rollback
|
||||
|
||||
Check the API source network scope. Check the base URL and credentials.
|
||||
|
||||
Check the request method, path, body, direct value bindings, and board permission.
|
||||
|
||||
For “invalid placeholder,” use `{option:name}` or `{param:name}`. Load queries can only reference options. The preview journal does not show credentials.
|
||||
|
||||
The journal shows the method, request ID, path template, status, and duration.
|
||||
|
||||
In a multi-instance deployment, all Homarr replicas must share Redis. Versioned cache invalidation is distributed
|
||||
through Redis; replicas connected to different Redis databases can serve stale query responses after an action.
|
||||
|
||||
## Correct a Mantine prop warning
|
||||
|
||||
`UNKNOWN_MANTINE_PROP` is a warning. Homarr passes the prop to Mantine.
|
||||
|
||||
Check the prop in the documentation for the installed Mantine version. `BLOCKED_CAPABILITY` identifies an unsafe capability.
|
||||
|
||||
Use safe widget options, temporary inputs, or named requests instead.
|
||||
|
||||
## Repair an existing item
|
||||
|
||||
The widget option definitions changed and the saved values are invalid. Open the item settings.
|
||||
|
||||
Correct the marked configuration values. Homarr does not infer widget option migrations.
|
||||
|
||||
## Roll back safely
|
||||
|
||||
Before an application upgrade, back up the database and preserve the exact `SECRET_ENCRYPTION_KEY`. The v2 schema keeps
|
||||
the physical v1 definition and secret tables readable by a v1 binary. Roll back the application without running
|
||||
manual cleanup, verify legacy widgets, and restore the database backup if the migration itself must be reversed.
|
||||
PocketBase Workshop data is a separate backup and restore operation.
|
||||
Preserve a database backup and the exact `SECRET_ENCRYPTION_KEY`. Roll back the Homarr application without manually
|
||||
removing the v1 tables. Workshop's PocketBase data has a separate backup lifecycle.
|
||||
Reference in new issue
Block a user