refactor: address adversarial widget architecture review
This commit is contained in:
1 parent
0ca62f1232
commit
9bf266935b
42 files changed
+460
-578
No files matched your search
@@ -8,8 +8,8 @@ tags:
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
Homarr keeps feature registration explicit and typed. There is no generator or generated registry to run after a
|
||||
change. A new feature is available when its typed metadata and lazy loader are registered.
|
||||
Homarr keeps feature registration explicit and typed. Feature registration has no generator or generated registry.
|
||||
A new feature is available when its typed metadata and lazy loader are registered.
|
||||
|
||||
## Add a widget
|
||||
|
||||
@@ -46,10 +46,24 @@ Keep the HTTP client and its capability-specific types in `packages/integrations
|
||||
implementation out of the initial server bundle and makes the registration easy to find.
|
||||
3. Implement only the interfaces required by the widgets that use the service.
|
||||
4. Add canonical documentation in `apps/docs/docs/integrations/<slug>/`. Its `index.ts` must satisfy
|
||||
`IntegrationDefinition` so invalid metadata fails type checking.
|
||||
`IntegrationDefinition` so invalid metadata fails type checking without widening the object. Use a type-only import
|
||||
and `satisfies IntegrationDefinition`; do not cast the object.
|
||||
|
||||
Beszel is a compact example with several widgets sharing one integration client.
|
||||
|
||||
## Write user documentation
|
||||
|
||||
Write for technically capable self-hosters. Keep each page short and operational.
|
||||
|
||||
- Start with one sentence describing what the integration or widget adds to Homarr.
|
||||
- Include prerequisites, credentials, permissions, destructive actions, and non-obvious limits only when they matter.
|
||||
- Use numbered steps only when order matters. Prefer the exact UI labels a user must select.
|
||||
- Do not add marketing, implementation history, architecture internals, or explanations of basic self-hosting concepts.
|
||||
- End when the user can configure and verify the feature; do not repeat the same information in a summary.
|
||||
|
||||
The usual page needs only an introduction and a `Configuration` section. Add `Notes` or `Troubleshooting` only for
|
||||
real caveats.
|
||||
|
||||
## Data and errors
|
||||
|
||||
- TanStack Query owns browser caching and refresh behavior. Redis owns shared server response caching.
|
||||
|
||||
@@ -110,6 +110,9 @@ The OpenAPI and MCP APIs include board management endpoints for common automatio
|
||||
- Set desktop and mobile home boards for the current user
|
||||
- Configure global board defaults such as public home boards and status behavior
|
||||
|
||||
Creating, duplicating, or reconfiguring a widget validates its integration selection on the server. The caller needs
|
||||
use access for each newly linked integration; unchanged links remain editable through normal board permissions.
|
||||
|
||||
Board layout responses identify each layout with a `mobile`, `base`, or `custom` role. Mobile and Base are protected. Layout-saving clients must preserve existing roles, keep Mobile at breakpoint `0`, keep Base as the highest breakpoint, and use unique custom breakpoints between them. The layout save operation returns the canonical saved layouts, including server-generated IDs for new custom layouts. A non-Base layout can be regenerated from Base with the protected reset operation.
|
||||
|
||||
Use the interactive API reference to inspect the exact request body for each endpoint under the `boards` and `settings` tags.
|
||||
|
||||
@@ -9,7 +9,7 @@ import { getRepresentativeLayoutWidth, projectBoardLayout } from "@homarr/boards
|
||||
import { getBoardLaneColumnCount, getRootSectionLane, getWidgetName } from "@homarr/definitions";
|
||||
import { useI18n } from "@homarr/translation/client";
|
||||
import { MaskedOrNormalImage } from "@homarr/ui";
|
||||
import { widgetCatalogIcons } from "@homarr/widgets/catalog";
|
||||
import { widgetCatalogIcons } from "@homarr/ui/widget-icons";
|
||||
|
||||
import type { Board } from "../../_types";
|
||||
import classes from "./_layout-preview.module.css";
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
import type { PropsWithChildren } from "react";
|
||||
|
||||
import { widgetKinds } from "@homarr/definitions";
|
||||
import { widgetCatalogIcons } from "@homarr/widgets/catalog";
|
||||
import { widgetCatalogIcons } from "@homarr/ui/widget-icons";
|
||||
|
||||
import { MainNavigation } from "~/components/layout/navigation";
|
||||
import { ClientShell } from "~/components/layout/shell";
|
||||
|
||||
@@ -4,7 +4,7 @@ import { IconLayoutGrid } from "@tabler/icons-react";
|
||||
import type { BoardPreviewData } from "@homarr/boards/layout-preview";
|
||||
import { projectBoardLayout } from "@homarr/boards/layout-preview";
|
||||
import { boardLanes, getBoardLaneColumnCount, getRootSectionLane } from "@homarr/definitions";
|
||||
import { widgetCatalogIcons } from "@homarr/widgets/catalog";
|
||||
import { widgetCatalogIcons } from "@homarr/ui/widget-icons";
|
||||
|
||||
import classes from "./board-layout-thumbnail.module.css";
|
||||
|
||||
|
||||
@@ -42,7 +42,7 @@ import { useSettings } from "@homarr/settings";
|
||||
import { useI18n } from "@homarr/translation/client";
|
||||
import { SelectableCard } from "@homarr/ui";
|
||||
import type { TablerIcon } from "@homarr/ui";
|
||||
import { widgetCatalogIcons } from "@homarr/widgets/catalog";
|
||||
import { widgetCatalogIcons } from "@homarr/ui/widget-icons";
|
||||
import { loadWidgetDefinition, reduceWidgetOptionsWithDefinition } from "@homarr/widgets/manifest";
|
||||
|
||||
import type { EmptySection } from "~/app/[locale]/boards/_types";
|
||||
|
||||
@@ -22,7 +22,7 @@ import { useCurrentLayout, useRequiredBoard } from "@homarr/boards/context";
|
||||
import { useEditMode } from "@homarr/boards/edit-mode";
|
||||
import { getBoardLaneColumnCount, getRootSectionLane, getWidgetName } from "@homarr/definitions";
|
||||
import { useI18n } from "@homarr/translation/client";
|
||||
import { widgetCatalogIcons } from "@homarr/widgets/catalog";
|
||||
import { widgetCatalogIcons } from "@homarr/ui/widget-icons";
|
||||
|
||||
import type { EmptySection } from "~/app/[locale]/boards/_types";
|
||||
import { useRegisteredGridEditors } from "~/components/board/sections/grid/grid-editor-registry";
|
||||
|
||||
Reference in new issue
Block a user