refactor: streamline widget and integration architecture

This commit is contained in:
ajnart committed 2026-08-23 22:33:29 +02:00
1 parent ec295fe26e
commit 425cb653a1
243 files changed
+5722 -2255

No files matched your search

@@ -6,8 +6,6 @@ import { optionsBuilder } from "../options";
export const { definition, componentLoader } = createWidgetDefinition("airQuality", {
icon: IconWind,
supportsAdvancedFocus: true,
queryKey: [["widget", "airQuality", "atLocation"]],
refetchInterval: 900,
queryMatcher: ({ input }, scope) => {
const location = scope.options.location;
if (location === null || typeof location !== "object" || !("latitude" in location) || !("longitude" in location)) {
@@ -6,9 +6,6 @@ import { optionsBuilder } from "../options";
export const { definition, componentLoader } = createWidgetDefinition("anchorNote", {
icon: IconNotes,
supportsAdvancedFocus: true,
queryKey: [["widget", "anchorNotes"]],
maxIntegrations: 1,
supportedIntegrations: ["anchor"],
createOptions() {
return optionsBuilder.from((factory) => ({
noteId: factory.anchorNote(),
-1
View File
@@ -16,7 +16,6 @@ import { optionsBuilder } from "../options";
export const { definition, componentLoader } = createWidgetDefinition("app", {
icon: IconApps,
supportsAdvancedFocus: false,
queryKeys: [[["app", "byId"]], [["widget", "app", "ping"]]],
createOptions(settings) {
return optionsBuilder.from(
(factory) => ({
@@ -6,7 +6,6 @@ import { optionsBuilder } from "../options";
export const { definition, componentLoader } = createWidgetDefinition("archiveTeamWarrior", {
icon: IconArchive,
supportsAdvancedFocus: true,
maxIntegrations: 1,
createOptions() {
return optionsBuilder.from((factory) => ({
showBroadcastMessage: factory.switch({
@@ -14,5 +13,4 @@ export const { definition, componentLoader } = createWidgetDefinition("archiveTe
}),
}));
},
supportedIntegrations: ["archiveTeamWarrior"],
}).withDynamicImport(() => import("./component"));
@@ -14,11 +14,7 @@ const hideUnlessAudiobookshelf = {
export const { definition, componentLoader } = createWidgetDefinition("audioStats", {
icon: IconHeadphones,
supportsAdvancedFocus: true,
queryKeys: [[["widget", "audioStats", "getStats"]], [["widget", "mediaServer", "getCurrentStreams"]]],
queryMatcher: matchesWidgetRuntimeQuery,
supportedIntegrations: ["navidrome", "audiobookshelf"],
integrationsRequired: true,
maxIntegrations: 1,
createOptions() {
return optionsBuilder.from(
(factory) => ({
-3
View File
@@ -6,9 +6,6 @@ import { optionsBuilder } from "../options";
export const { definition, componentLoader } = createWidgetDefinition("bazarr", {
supportsAdvancedFocus: true,
icon: IconBadgeCc,
supportedIntegrations: ["bazarr"],
integrationsRequired: true,
maxIntegrations: 1,
createOptions() {
return optionsBuilder.from((factory) => ({
showMissingEpisodes: factory.switch({
@@ -6,7 +6,6 @@ import { optionsBuilder } from "../options";
export const { definition, componentLoader } = createWidgetDefinition("beszelAlerts", {
icon: IconBell,
queryKey: [["widget", "beszel", "getAlerts"]],
queryMatcher(query, scope) {
const hasRuntimeAlertsQuery = scope.runtimeQueries.some(({ path }) => path.at(-1) === "getAlerts");
if (hasRuntimeAlertsQuery) return matchesWidgetRuntimeQuery(query, scope);
@@ -17,8 +16,6 @@ export const { definition, componentLoader } = createWidgetDefinition("beszelAle
maxHistoryItems: scope.options.maxHistoryItems,
});
},
supportedIntegrations: ["beszel", "mock"],
integrationsRequired: true,
createOptions() {
return optionsBuilder.from((factory) => ({
showHistory: factory.switch({ defaultValue: true }),
@@ -6,9 +6,6 @@ import { optionsBuilder } from "../options";
export const { definition, componentLoader } = createWidgetDefinition("beszelSystemGrid", {
icon: IconLayoutGrid,
queryKey: [["widget", "beszel", "getSystems"]],
supportedIntegrations: ["beszel", "mock"],
integrationsRequired: true,
createOptions() {
return optionsBuilder.from((factory) => ({
statusFilter: factory.select({
@@ -17,7 +17,6 @@ const timePeriodOptions = [
export const { definition, componentLoader } = createWidgetDefinition("beszelSystemStats", {
icon: IconChartAreaLine,
queryKeys: [[["widget", "beszel", "getSystems"]], [["widget", "beszel", "getSystemStats"]]],
queryMatcher(query, scope) {
if (query.path.at(-1) === "getSystems") {
return widgetQueryInputMatches(query.input, { integrationIds: scope.integrationIds });
@@ -40,8 +39,6 @@ export const { definition, componentLoader } = createWidgetDefinition("beszelSys
(dockerEnabled && widgetQueryInputMatches(query.input, { ...expected, includeDocker: true }))
);
},
supportedIntegrations: ["beszel", "mock"],
integrationsRequired: true,
createOptions() {
return optionsBuilder.from((factory) => ({
systemId: factory.integrationSelect({
@@ -28,13 +28,10 @@ const sortDirectionOptions = [
export const { definition, componentLoader } = createWidgetDefinition("beszelSystemTable", {
icon: IconTable,
queryKeys: [[["widget", "beszel", "getSystems"]], [["widget", "beszel", "getSystemStats"]]],
queryMatcher: (query, scope) =>
query.path.at(-1) === "getSystems"
? widgetQueryInputMatches(query.input, { integrationIds: scope.integrationIds })
: matchesWidgetRuntimeQuery(query, scope),
supportedIntegrations: ["beszel", "mock"],
integrationsRequired: true,
createOptions() {
return optionsBuilder.from(
(factory) => ({
-1
View File
@@ -12,7 +12,6 @@ import { createDirectBookmark, getBookmarkFaviconUrl, getDirectBookmarkUrl } fro
export const { definition, componentLoader } = createWidgetDefinition("bookmarks", {
icon: IconBookmark,
supportsAdvancedFocus: true,
queryKey: [["app", "byIds"]],
createOptions() {
return optionsBuilder.from((factory) => ({
title: factory.text(),
-4
View File
@@ -1,7 +1,6 @@
import { IconCalendar } from "@tabler/icons-react";
import { z } from "zod/v4";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { radarrReleaseTypes } from "@homarr/integrations/types";
import { createWidgetDefinition, matchesWidgetRuntimeQuery } from "../definition";
@@ -10,7 +9,6 @@ import { optionsBuilder } from "../options";
export const { definition, componentLoader } = createWidgetDefinition("calendar", {
icon: IconCalendar,
supportsAdvancedFocus: true,
queryKey: [["widget", "calendar", "findAllEvents"]],
queryMatcher: matchesWidgetRuntimeQuery,
createOptions() {
return optionsBuilder.from((factory) => ({
@@ -34,6 +32,4 @@ export const { definition, componentLoader } = createWidgetDefinition("calendar"
}),
}));
},
supportedIntegrations: getIntegrationKindsByCategory("calendar"),
integrationsRequired: false,
}).withDynamicImport(() => import("./component"));
+1 -119
View File
@@ -1,119 +1 @@
import {
IconActivityHeartbeat,
IconAd,
IconApi,
IconApps,
IconArchive,
IconBadgeCc,
IconBatteryCharging,
IconBell,
IconBinaryTree,
IconBookmark,
IconBrandDocker,
IconBrandMinecraft,
IconBrowser,
IconBuildingBank,
IconBusStop,
IconCalendar,
IconChartAreaLine,
IconChartBar,
IconClock,
IconClockPlay,
IconCloud,
IconDeviceCctv,
IconDeviceGamepad,
IconDownload,
IconFileText,
IconGraphFilled,
IconHourglass,
IconHeadphones,
IconHeartRateMonitor,
IconHeartbeat,
IconLayoutGrid,
IconMessage,
IconMovie,
IconNotes,
IconPhoto,
IconReportSearch,
IconRocket,
IconRobot,
IconRoute,
IconRss,
IconServer2,
IconShieldCheck,
IconShieldLock,
IconSpeedboat,
IconTable,
IconTicket,
IconTopologyFull,
IconTransform,
IconVideo,
IconWall,
IconWind,
IconZoomQuestion,
} from "@tabler/icons-react";
import type { WidgetKind } from "@homarr/definitions";
import type { TablerIcon } from "@homarr/ui";
export const widgetCatalogIcons: Record<WidgetKind, TablerIcon> = {
clock: IconClock,
weather: IconCloud,
airQuality: IconWind,
countdown: IconHourglass,
timer: IconClockPlay,
app: IconApps,
assistant: IconRobot,
iframe: IconBrowser,
video: IconDeviceCctv,
notebook: IconNotes,
anchorNote: IconNotes,
dnsHoleSummary: IconAd,
dnsHoleControls: IconDeviceGamepad,
"smartHome-entityState": IconBinaryTree,
"smartHome-executeAutomation": IconBinaryTree,
stockPrice: IconBuildingBank,
mediaServer: IconVideo,
calendar: IconCalendar,
downloads: IconDownload,
"mediaRequests-requestList": IconZoomQuestion,
"mediaRequests-requestStats": IconChartBar,
mediaTranscoding: IconTransform,
mediaMissing: IconMovie,
minecraftServerStatus: IconBrandMinecraft,
networkControllerSummary: IconTopologyFull,
networkControllerStatus: IconTopologyFull,
rssFeed: IconRss,
bookmarks: IconBookmark,
indexerManager: IconReportSearch,
healthMonitoring: IconHeartRateMonitor,
releases: IconRocket,
mediaReleases: IconTicket,
dockerContainers: IconBrandDocker,
firewall: IconWall,
notifications: IconMessage,
systemResources: IconGraphFilled,
coolify: IconCloud,
systemDisks: IconServer2,
timetable: IconBusStop,
"immich-serverStats": IconGraphFilled,
"immich-albumCarousel": IconPhoto,
paperlessNgx: IconFileText,
patchmon: IconShieldCheck,
bazarr: IconBadgeCc,
tracearr: IconActivityHeartbeat,
speedtestTracker: IconSpeedboat,
uptimeKuma: IconHeartbeat,
audioStats: IconHeadphones,
umami: IconChartBar,
vpn: IconShieldLock,
archiveTeamWarrior: IconArchive,
ups: IconBatteryCharging,
beszelSystemTable: IconTable,
beszelSystemGrid: IconLayoutGrid,
beszelAlerts: IconBell,
beszelSystemStats: IconChartAreaLine,
traefik: IconRoute,
customApi: IconApi,
wud: IconBrandDocker,
};
export { widgetCatalogIcons } from "@homarr/ui/widget-icons";
-1
View File
@@ -15,7 +15,6 @@ const timeZoneOptions = getTimeZoneOptions();
export const { definition, componentLoader } = createWidgetDefinition("clock", {
icon: IconClock,
supportsAdvancedFocus: true,
queryKey: [["widget", "weather", "atLocation"]],
queryMatcher: ({ input }, scope) => {
const location = scope.options.weatherLocation;
if (
-1
View File
@@ -19,7 +19,6 @@ export const { definition, componentLoader } = createWidgetDefinition("coolify",
}),
}));
},
supportedIntegrations: ["coolify"],
errors: {
INTERNAL_SERVER_ERROR: {
icon: IconServerOff,
+90 -12
View File
@@ -4,13 +4,14 @@ import type { QueryClient, QueryKey } from "@tanstack/react-query";
import { hashKey } from "@tanstack/react-query";
import type { DefaultErrorData } from "@trpc/server/unstable-core-do-not-import";
import type { IntegrationKind, WidgetKind } from "@homarr/definitions";
import type { IntegrationKind, NativeFeatureCapabilityDescriptor, WidgetKind } from "@homarr/definitions";
import { widgetFeatureCatalog } from "@homarr/definitions";
import type { ServerSettings } from "@homarr/server-settings";
import type { SettingsContextProps } from "@homarr/settings/creator";
import type { stringOrTranslation } from "@homarr/translation";
import type { TablerIcon } from "@homarr/ui";
import type { WidgetImports } from ".";
import type { WidgetImports } from "./registry";
import type { inferOptionsFromCreator, WidgetOptionsRecord } from "./options";
export interface WidgetContextMenuAction {
@@ -73,13 +74,86 @@ export interface WidgetContextActionProps {
widgetRuntimeRef: WidgetRuntimeRef;
}
type WidgetFeatureCapability<TKind extends WidgetKind> = (typeof widgetFeatureCatalog)[TKind] extends {
capability: infer TCapability extends NativeFeatureCapabilityDescriptor;
}
? TCapability
: never;
type WidgetFeatureIntegrationDefinition<TKind extends WidgetKind> = [WidgetFeatureCapability<TKind>] extends [never]
? object
: {
supportedIntegrations: WidgetFeatureCapability<TKind>["integrations"][number][];
integrationsRequired: WidgetFeatureCapability<TKind> extends { connectionOptional: true } ? false : true;
} & (WidgetFeatureCapability<TKind> extends { serverMaxIntegrations: infer TMax extends number }
? { maxIntegrations: TMax }
: object);
type CatalogOwnedWidgetDefinitionKey =
| "kind"
| "supportedIntegrations"
| "integrationsRequired"
| "maxIntegrations"
| "queryKey"
| "queryKeys"
| "refetchInterval";
type WidgetDefinitionInput = Omit<WidgetDefinition, CatalogOwnedWidgetDefinitionKey>;
type WidgetDefinitionInputWithoutCatalogMetadata<TDefinition extends WidgetDefinitionInput> = TDefinition & {
[TKey in CatalogOwnedWidgetDefinitionKey]?: never;
};
type ResolvedWidgetDefinition<TKind extends WidgetKind, TDefinition extends WidgetDefinitionInput> = TDefinition &
WidgetFeatureIntegrationDefinition<TKind> & {
kind: TKind;
queryKey?: QueryKey;
queryKeys?: readonly QueryKey[];
refetchInterval?: number | null;
};
const resolveWidgetDefinition = <TKind extends WidgetKind, TDefinition extends WidgetDefinitionInput>(
kind: TKind,
definition: WidgetDefinitionInputWithoutCatalogMetadata<TDefinition>,
): ResolvedWidgetDefinition<TKind, TDefinition> => {
const descriptor = widgetFeatureCatalog[kind];
const resolvedDefinition: WidgetDefinition = {
...definition,
kind,
};
if ("capability" in descriptor) {
const capability = descriptor.capability;
const connectionOptional = "connectionOptional" in capability && capability.connectionOptional === true;
resolvedDefinition.supportedIntegrations = [...capability.integrations];
resolvedDefinition.integrationsRequired = !connectionOptional;
if ("serverMaxIntegrations" in capability && capability.serverMaxIntegrations !== undefined) {
resolvedDefinition.maxIntegrations = capability.serverMaxIntegrations;
}
}
if ("query" in descriptor) {
const queryKeys: QueryKey[] = descriptor.query.paths.map((path) => [path]);
if (queryKeys.length === 1) {
resolvedDefinition.queryKey = queryKeys[0];
} else {
resolvedDefinition.queryKeys = queryKeys;
}
if ("refetchIntervalSeconds" in descriptor.query) {
resolvedDefinition.refetchInterval = descriptor.query.refetchIntervalSeconds;
}
}
return resolvedDefinition as ResolvedWidgetDefinition<TKind, TDefinition>;
};
const createWithDynamicImport =
<TKind extends WidgetKind, TDefinition extends WidgetDefinition>(kind: TKind, definition: TDefinition) =>
<TKind extends WidgetKind, TDefinition extends WidgetDefinitionInput>(
kind: TKind,
definition: ResolvedWidgetDefinition<TKind, TDefinition>,
) =>
(componentLoader: () => LoaderComponent<WidgetComponentProps<TKind>>) => ({
definition: {
...definition,
kind,
},
definition,
kind,
componentLoader,
});
@@ -93,14 +167,18 @@ export type Prefetch<TKind extends WidgetKind> = (
}[],
) => Promise<void>;
export const createWidgetDefinition = <TKind extends WidgetKind, TDefinition extends WidgetDefinition>(
export const createWidgetDefinition = <TKind extends WidgetKind, TDefinition extends WidgetDefinitionInput>(
kind: TKind,
definition: TDefinition,
) => ({
withDynamicImport: createWithDynamicImport(kind, definition),
});
definition: WidgetDefinitionInputWithoutCatalogMetadata<TDefinition>,
) => {
const resolvedDefinition = resolveWidgetDefinition(kind, definition);
return {
withDynamicImport: createWithDynamicImport(kind, resolvedDefinition),
};
};
export interface WidgetDefinition {
kind?: WidgetKind;
icon: TablerIcon;
supportsAdvancedFocus?: boolean;
queryKey?: QueryKey;
@@ -1,6 +1,5 @@
import { IconDeviceGamepad, IconServerOff } from "@tabler/icons-react";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { createWidgetDefinition } from "../../definition";
import { optionsBuilder } from "../../options";
@@ -10,8 +9,6 @@ export const widgetKind = "dnsHoleControls";
export const { definition, componentLoader } = createWidgetDefinition(widgetKind, {
supportsAdvancedFocus: false,
icon: IconDeviceGamepad,
queryKey: [["widget", "dnsHole"]],
refetchInterval: 10,
createOptions() {
return optionsBuilder.from((factory) => ({
showToggleAllButtons: factory.switch({
@@ -19,7 +16,6 @@ export const { definition, componentLoader } = createWidgetDefinition(widgetKind
}),
}));
},
supportedIntegrations: getIntegrationKindsByCategory("dnsHole"),
errors: {
INTERNAL_SERVER_ERROR: {
icon: IconServerOff,
@@ -1,6 +1,5 @@
import { IconAd, IconServerOff } from "@tabler/icons-react";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { createWidgetDefinition } from "../../definition";
import { optionsBuilder } from "../../options";
@@ -10,8 +9,6 @@ export const widgetKind = "dnsHoleSummary";
export const { definition, componentLoader } = createWidgetDefinition(widgetKind, {
supportsAdvancedFocus: false,
icon: IconAd,
queryKey: [["widget", "dnsHole"]],
refetchInterval: 10,
createOptions() {
return optionsBuilder.from((factory) => ({
usePiHoleColors: factory.switch({
@@ -30,7 +27,6 @@ export const { definition, componentLoader } = createWidgetDefinition(widgetKind
}),
}));
},
supportedIntegrations: getIntegrationKindsByCategory("dnsHole"),
errors: {
INTERNAL_SERVER_ERROR: {
icon: IconServerOff,
-2
View File
@@ -27,8 +27,6 @@ const columnTranslationKeyMap = {
export const { definition, componentLoader } = createWidgetDefinition("dockerContainers", {
icon: IconBrandDocker,
supportsAdvancedFocus: true,
queryKey: [["docker", "getContainers"]],
refetchInterval: 30,
createOptions() {
return optionsBuilder.from(
(factory) => ({
Binary file not shown.

After

Width:  |  Height:  |  Size: 116 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 210 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 76 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 122 KiB

@@ -0,0 +1,152 @@
---
title: "Download Client"
description: "Allows you to view and manage your Downloads from both Torrent and Usenet clients."
hide_title: true
---
import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
import { aria2Integration } from "@site/docs/integrations/aria2";
import { delugeIntegration } from "@site/docs/integrations/deluge";
import { nzbgetIntegration } from "@site/docs/integrations/nzbget";
import { qBittorentIntegration } from "@site/docs/integrations/q-bittorent";
import { sabnzbdIntegration } from "@site/docs/integrations/sabnzbd";
import { transmissionIntegration } from "@site/docs/integrations/transmission";
import { slskdIntegration } from "@site/docs/integrations/slskd";
import { AddingWidget } from "@site/src/components/widgets/adding";
import { WidgetConfig } from "@site/src/components/widgets/configuration";
import { WidgetHeader } from "@site/src/components/widgets/header";
import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
import { downloadsWidget } from ".";
<WidgetHeader widget={downloadsWidget} categories={["Torrent client", "Usenet client", "Downloads"]} />
This widget displays torrent, Usenet, and miscellaneous download jobs, along with their progress and other relevant information. It supports 7 download client integrations and provides a rich, responsive table interface.
### Screenshots
import downloadsCard from "./img/screenshot.png";
import contextMenuImg from "./img/context-menu.png";
import advancedViewImg from "./img/advanced-view.png";
import filterPanelImg from "./img/filter-panel.png";
<div>
<img src={downloadsCard} alt="Downloads widget showing torrent and usenet items" width={128 * 4} />
</div>
#### Download-row context menu
<div>
<img src={contextMenuImg} alt="Downloads row context menu with pause, delete, and copy actions" width={128 * 4} />
</div>
#### Advanced view
<div>
<img
src={advancedViewImg}
alt="Downloads widget in advanced view with stats, sortable columns, and expanded details"
width={128 * 6}
/>
</div>
#### Advanced filter panel
<div>
<img src={filterPanelImg} alt="Downloads advanced view with the status filter panel open" width={128 * 6} />
</div>
### Features
- **Responsive compact table** — in compact mode, selected columns adapt to both widget width and height; narrow or short tiles hide speed/state columns, and the shortest tiles also hide the ETA column
- **Sortable columns** — click any sortable column header to sort the current view; the configured default controls the initial column and direction
- **Column customization** — choose which columns to display, then hover a header to reveal its grab handle for reordering or drag its edge to resize it; layouts save automatically per widget
- **Download-row context menu** — copy a download name or ID from any row; pause, resume, and delete actions appear when you have Interact access to that integration
- **Row expansion** — click any row to see full details inline without opening a separate modal
- **Hover tooltips** — hover a download name to see size, speeds, ETA, ratio, and category; open tooltips close when switching between compact and advanced mode
- **Global stats bar** — show queue progress, downloaded/total size, transfer speeds, global torrent ratio, and per-state counts in compact mode; advanced view always includes it
- **Client filtering** — filter downloads by integration or status using the footer filter panel
- **Global controls** — pause/resume actionable queues from the footer bar, limited to selected integrations where you have Interact access
- **Status indicators** — color-coded badges show download state at a glance
- **Speed overview** — total download and upload speeds for the selected clients are displayed in the footer
:::note
Compact layouts use both dimensions: below 500px wide, speed columns are hidden; below 300px wide, the ETA and state
columns are hidden too. A tile shorter than 180px hides speed and state columns, and a tile shorter than 120px also
hides ETA. The footer is hidden below 96px in compact mode. Advanced view bypasses these compact size reductions,
keeps the selected column set, and always includes the stats bar and footer controls, with the filter panel available
from the footer.
The filter panel changes the visible rows. Its client/status filters also change the stats bar's progress, size, and
state counts, while transfer-speed totals summarize the selected clients and the global torrent ratio summarizes the
selected torrent clients. The configured category/label filter can optionally be applied to the global torrent ratio
through **Use category filter for global torrent ratio**; footer client/status filters do not change that ratio.
The per-item **Ratio** is sent bytes divided by the item's total size. **Global Ratio** is total uploaded bytes divided
by total downloaded bytes.
Mutation controls depend on the integration's Interact permission. Users without that permission can still view rows and
use the row menu's copy actions. `slskd` is list-only: its pause, resume, and delete operations are no-ops, so those
controls have no effect for that client even when Interact permission exposes them.
The screenshot above is a Downloads row menu, separate from the shared widget context menu. When board right-click menus
are enabled, the shared menu provides widget-level actions such as advanced view, widget options, refresh, and settings.
:::
### Supported Integrations
<WidgetIntegrations
items={[
{
integration: sabnzbdIntegration,
note: "Usenet client",
},
{
integration: nzbgetIntegration,
note: "Usenet client",
},
{
integration: delugeIntegration,
note: "Torrent client",
},
{
integration: transmissionIntegration,
note: "Torrent client",
},
{
integration: qBittorentIntegration,
note: "Torrent client",
},
{
integration: aria2Integration,
note: "Multi-protocol download client",
},
{
integration: slskdIntegration,
note: "Soulseek client (list-only; mutation controls are no-ops)",
},
]}
/>
### Interactions
- **Right-click** any download to copy its name or ID; pause, resume, and delete are available only with Interact access
- **Click** any row to expand it and see full download details inline
- **Hover** a download name for a quick stats tooltip
- **Stats toggle** — show or hide the global stats bar in compact mode; advanced view always shows the stats bar without
changing the compact choice
- **Pause / Resume** actionable queues using the footer controls
- **Filter** rows by integration or status using the filter button in the footer
- **Sort** by clicking sortable column headers; the default sort is configured per widget, while header changes apply to the current view
<WidgetInteractionGuide />
### Adding the widget
<AddingWidget />
### Configuration
<WidgetConfig configuration={downloadsWidget.configuration} />
@@ -0,0 +1,102 @@
import { WidgetDefinition } from "@site/src/types";
import { IconDownload } from "@tabler/icons-react";
const columnsList = [
"name",
"progress",
"size",
"downSpeed",
"upSpeed",
"time",
"state",
"added",
"ratio",
"received",
"sent",
"category",
"integration",
"index",
"type",
];
const sortColumns = columnsList.filter((c) => !["state", "category", "integration"].includes(c));
export const downloadsWidget: WidgetDefinition = {
icon: IconDownload,
name: "Download Client",
description: "Allows you to view and manage your Downloads from both Torrent and Usenet clients.",
path: "../../widgets/downloads",
configuration: {
items: [
{
name: "Columns to show",
description:
"Select the columns you want to display in the widget. Compact layouts automatically hide/show selected columns based on widget width and height; advanced view keeps the selected columns visible.",
values: `List of columns: ${columnsList.join(", ")}`,
defaultValue: ["name", "progress", "downSpeed", "time", "state"].join(", "),
},
{
name: "Default sort column",
description:
"The column used for initial sorting when the widget loads. Clicking a column header changes the current view only.",
defaultValue: "progress",
values: `List of columns: ${sortColumns.join(", ")}`,
},
{
name: "Invert sorting",
description: "This sets the initial sorting direction.",
values: { type: "boolean" },
defaultValue: "no",
},
{
name: "Show usenet entries marked as completed",
description: "This will show entries that have been completed in your Usenet client.",
values: { type: "boolean" },
defaultValue: "yes",
},
{
name: "Show torrent entries marked as completed",
description: "This will show entries that have been completed in your Torrent client.",
values: { type: "boolean" },
defaultValue: "yes",
},
{
name: "Show Miscellaneous entries marked as completed",
description: "This will show entries that have been completed in your Miscellaneous client.",
values: { type: "boolean" },
defaultValue: "yes",
},
{
name: "Hide completed torrent under this threshold (in kiB/s)",
description: "This will hide completed torrent entries whose upload speed is below the specified threshold.",
values: "Any number above 0, 0 to disable",
defaultValue: "0",
},
{
name: "Categories/labels to filter",
description: "You can filter the items by categories or labels. Use a comma to separate multiple values.",
values: "Comma-separated list of categories or labels",
defaultValue: "-",
},
{
name: "Filter as a whitelist",
description:
"If enabled, only items that match the filter will be shown. If disabled, items that do not match the filter will be hidden.",
values: { type: "boolean" },
defaultValue: "no",
},
{
name: "Use category filter for global torrent ratio",
description:
"When enabled, the configured category/label filter is applied to the global torrent ratio. Footer client/status filters do not change this ratio.",
values: { type: "boolean" },
defaultValue: "yes",
},
{
name: "Limit items per integration",
description: "This will limit the number of items shown per integration, not globally.",
values: "Any whole number from 1 upward",
defaultValue: "50",
},
],
},
};
+2 -5
View File
@@ -1,4 +1,3 @@
import { IconDownload } from "@tabler/icons-react";
import { z } from "zod/v4";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
@@ -6,6 +5,7 @@ import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { createWidgetDefinition, widgetQueryInputMatches } from "../definition";
import { optionsBuilder } from "../options";
import { DOWNLOAD_COLUMN_ACCESSORS } from "./helpers";
import { widgetIcon } from "./module.generated";
const sortColumns = [
"name",
@@ -23,15 +23,13 @@ const sortColumns = [
] as const satisfies readonly (typeof DOWNLOAD_COLUMN_ACCESSORS)[number][];
export const { definition, componentLoader } = createWidgetDefinition("downloads", {
icon: IconDownload,
icon: widgetIcon,
supportsAdvancedFocus: true,
queryKey: [["widget", "downloads", "getJobsAndStatuses"]],
queryMatcher: ({ input }, scope) =>
widgetQueryInputMatches(input, {
integrationIds: scope.integrationIds,
limitPerIntegration: scope.options.limitPerIntegration,
}),
refetchInterval: 10,
createOptions() {
return optionsBuilder.from(
(factory) => ({
@@ -111,5 +109,4 @@ export const { definition, componentLoader } = createWidgetDefinition("downloads
},
);
},
supportedIntegrations: getIntegrationKindsByCategory("downloadClient"),
}).withDynamicImport(() => import("./component"));
@@ -0,0 +1,3 @@
// This file is generated by pnpm widgets:sync. Do not edit it directly.
export { IconDownload as widgetIcon } from "@tabler/icons-react";
+38
View File
@@ -0,0 +1,38 @@
import { defineWidgetModule } from "@homarr/definitions";
export default defineWidgetModule({
kind: "downloads",
icon: "IconDownload",
clientEntry: ".",
documentation: {
slug: "downloads",
sourceDirectory: "docs",
},
integration: {
categories: ["downloadClient"],
},
operations: [
{
name: "getJobsAndStatuses",
path: ["widget", "downloads", "getJobsAndStatuses"],
client: {
refetchIntervalSeconds: 10,
staleTimeSeconds: 10,
persist: true,
},
serverCache: {
namespace: "downloads:jobs-and-status",
ttlMs: 10 * 1000,
scope: "integration",
},
},
],
routers: [
{
namespace: "downloads",
module: "./downloads",
exportName: "downloadsRouter",
mcp: true,
},
],
});
@@ -12,7 +12,7 @@ export interface BaseWidgetErrorProps {
icon: TablerIcon;
message: stringOrTranslation;
showLogsLink?: boolean;
onRetry: () => void;
onRetry?: () => void;
}
export const BaseWidgetError = (props: BaseWidgetErrorProps) => {
@@ -39,9 +39,11 @@ export const BaseWidgetError = (props: BaseWidgetErrorProps) => {
)}
</Stack>
<Button onClick={props.onRetry} size="sm" variant="light">
{tCommon("action.tryAgain")}
</Button>
{props.onRetry && (
<Button onClick={props.onRetry} size="sm" variant="light">
{tCommon("action.tryAgain")}
</Button>
)}
</Stack>
);
};
-3
View File
@@ -1,6 +1,5 @@
import { IconWall, IconWallOff } from "@tabler/icons-react";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { createWidgetDefinition } from "../definition";
import { optionsBuilder } from "../options";
@@ -8,11 +7,9 @@ import { optionsBuilder } from "../options";
export const { definition, componentLoader } = createWidgetDefinition("firewall", {
icon: IconWall,
supportsAdvancedFocus: true,
refetchInterval: 10,
createOptions() {
return optionsBuilder.from(() => ({}));
},
supportedIntegrations: getIntegrationKindsByCategory("firewall"),
errors: {
INTERNAL_SERVER_ERROR: {
icon: IconWallOff,
@@ -0,0 +1,14 @@
// This file is generated by pnpm widgets:sync. Do not edit it directly.
import type * as widgetModule0 from "../downloads";
import type * as widgetModule1 from "../weather";
export const generatedWidgetModuleLoaders = {
downloads: () => import("../downloads"),
weather: () => import("../weather"),
};
export interface GeneratedWidgetImports {
downloads: typeof widgetModule0;
weather: typeof widgetModule1;
}
@@ -1,6 +1,5 @@
import { IconHeartRateMonitor, IconServerOff } from "@tabler/icons-react";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { createWidgetDefinition } from "../definition";
import { optionsBuilder } from "../options";
@@ -9,8 +8,6 @@ import { createStorageVolumeMultiSelectOptions } from "../storage-volume-options
export const { definition, componentLoader } = createWidgetDefinition("healthMonitoring", {
icon: IconHeartRateMonitor,
supportsAdvancedFocus: true,
queryKeys: [[["integration", "byIds"]], [["widget", "healthMonitoring"]]],
refetchInterval: 10,
createOptions() {
return optionsBuilder.from(
(factory) => ({
@@ -114,9 +111,6 @@ export const { definition, componentLoader } = createWidgetDefinition("healthMon
},
);
},
supportedIntegrations: getIntegrationKindsByCategory("healthMonitoring").filter(
(kind) => kind !== "patchmon" && kind !== "wud",
),
errors: {
INTERNAL_SERVER_ERROR: {
icon: IconServerOff,
@@ -52,7 +52,6 @@ const createOptions = () =>
export const { definition, componentLoader } = createWidgetDefinition("immich-albumCarousel", {
icon: IconPhoto,
supportsAdvancedFocus: true,
queryKey: [["widget", "immich", "getAlbum"]],
queryMatcher: ({ input }, scope) =>
widgetQueryInputMatches(input, {
integrationId: scope.integrationIds[0] ?? "",
@@ -61,10 +60,6 @@ export const { definition, componentLoader } = createWidgetDefinition("immich-al
? scope.options.albumId
: undefined,
}),
refetchInterval: null,
supportedIntegrations: ["immich"],
integrationsRequired: true,
maxIntegrations: 1,
contextActions: ({ widgetRuntimeRef }) => {
const actions = widgetRuntimeRef.current.actions;
return [
@@ -6,12 +6,7 @@ import { optionsBuilder } from "../../options";
export const { definition, componentLoader } = createWidgetDefinition("immich-serverStats", {
icon: IconGraphFilled,
supportsAdvancedFocus: true,
queryKeys: [[["widget", "immich", "getServerStats"]], [["widget", "immich", "getAlbums"]]],
queryMatcher: matchesWidgetRuntimeQuery,
refetchInterval: null,
supportedIntegrations: ["immich"],
integrationsRequired: true,
maxIntegrations: 1,
createOptions() {
return optionsBuilder.from((factory) => ({
showUsers: factory.switch({
-3
View File
@@ -1,3 +0,0 @@
import type { WidgetKind } from "@homarr/definitions";
export type WidgetImportRecord = Record<WidgetKind, unknown>;
+7 -166
View File
@@ -1,72 +1,6 @@
import type { ComponentType } from "react";
import type { Loader } from "next/dynamic";
import dynamic from "next/dynamic";
import { Center, Loader as UiLoader } from "@mantine/core";
import type { IntegrationKind, WidgetKind } from "@homarr/definitions";
import * as anchorNote from "./anchor-note";
import * as audioStats from "./audio-stats";
import * as app from "./app";
import * as archiveTeamWarrior from "./archive-team-warrior";
import * as bookmarks from "./bookmarks";
import * as bazarr from "./bazarr";
import * as calendar from "./calendar";
import * as clock from "./clock";
import * as coolify from "./coolify";
import type { WidgetComponentProps } from "./definition";
import * as dnsHoleControls from "./dns-hole/controls";
import * as dnsHoleSummary from "./dns-hole/summary";
import * as dockerContainers from "./docker";
import * as downloads from "./downloads";
import * as firewall from "./firewall";
import * as healthMonitoring from "./health-monitoring";
import * as iframe from "./iframe";
import * as immichAlbumCarousel from "./immich/album-carousel";
import * as immichServerStats from "./immich/server-stats";
import type { WidgetImportRecord } from "./import";
import * as indexerManager from "./indexer-manager";
import * as mediaReleases from "./media-releases";
import * as mediaRequestsList from "./media-requests/list";
import * as mediaRequestsStats from "./media-requests/stats";
import * as mediaServer from "./media-server";
import * as mediaTranscoding from "./media-transcoding";
import * as mediaMissing from "./media-missing";
import * as minecraftServerStatus from "./minecraft/server-status";
import * as networkControllerStatus from "./network-controller/network-status";
import * as networkControllerSummary from "./network-controller/summary";
import * as notebook from "./notebook";
import * as paperlessNgx from "./paperless-ngx";
import * as patchmon from "./patchmon";
import * as notifications from "./notifications";
import * as releases from "./releases";
import * as rssFeed from "./rssFeed";
import * as smartHomeEntityState from "./smart-home/entity-state";
import * as smartHomeExecuteAutomation from "./smart-home/execute-automation";
import * as speedtestTracker from "./speedtest-tracker";
import * as uptimeKuma from "./uptime-kuma";
import * as stockPrice from "./stocks";
import * as systemDisks from "./system-disks";
import * as systemResources from "./system-resources";
import * as timetable from "./timetable";
import * as traefik from "./traefik";
import * as tracearr from "./tracearr";
import * as umami from "./umami";
import * as ups from "./ups";
import * as vpn from "./vpn";
import * as beszelSystemTable from "./beszel-system-table";
import * as beszelSystemGrid from "./beszel-system-grid";
import * as beszelAlerts from "./beszel-alerts";
import * as beszelSystemStats from "./beszel-system-stats";
import * as video from "./video";
import * as weather from "./weather";
import * as airQuality from "./air-quality";
import * as countdown from "./countdown";
import * as timer from "./timer";
import * as customApi from "./custom-api";
import * as assistant from "./assistant";
import * as wud from "./wud";
export { AssistantWidgetRendererProvider } from "./assistant/context";
export type {
NormalizedWidgetQuery,
WidgetDefinition,
@@ -89,102 +23,9 @@ export {
} from "./definition";
export type { WidgetComponentProps };
export type { WidgetOptionDefinition, WidgetOptionType } from "./options";
export { AssistantWidgetRendererProvider } from "./assistant/context";
export const widgetImports = {
clock,
weather,
airQuality,
countdown,
timer,
app,
archiveTeamWarrior,
anchorNote,
notebook,
iframe,
video,
dnsHoleSummary,
dnsHoleControls,
"smartHome-entityState": smartHomeEntityState,
"smartHome-executeAutomation": smartHomeExecuteAutomation,
stockPrice,
mediaServer,
calendar,
downloads,
"mediaRequests-requestList": mediaRequestsList,
"mediaRequests-requestStats": mediaRequestsStats,
mediaMissing,
networkControllerSummary,
networkControllerStatus,
rssFeed,
bookmarks,
bazarr,
indexerManager,
healthMonitoring,
mediaTranscoding,
minecraftServerStatus,
dockerContainers,
releases,
firewall,
notifications,
mediaReleases,
systemResources,
coolify,
systemDisks,
timetable,
"immich-serverStats": immichServerStats,
"immich-albumCarousel": immichAlbumCarousel,
paperlessNgx,
patchmon,
tracearr,
speedtestTracker,
uptimeKuma,
audioStats,
umami,
vpn,
ups,
beszelSystemTable,
beszelSystemGrid,
beszelAlerts,
beszelSystemStats,
traefik,
customApi,
assistant,
wud,
} satisfies WidgetImportRecord;
export type WidgetImports = typeof widgetImports;
export type WidgetImportKey = keyof WidgetImports;
const loadedComponents = new Map<WidgetKind, ComponentType<WidgetComponentProps<WidgetKind>>>();
export const loadWidgetDynamic = <TKind extends WidgetKind>(kind: TKind) => {
const existingComponent = loadedComponents.get(kind);
if (existingComponent) return existingComponent;
const newlyLoadedComponent = dynamic<WidgetComponentProps<TKind>>(
widgetImports[kind].componentLoader as Loader<WidgetComponentProps<TKind>>,
{
loading: () => (
<Center w="100%" h="100%">
<UiLoader />
</Center>
),
},
);
loadedComponents.set(kind, newlyLoadedComponent as never);
return newlyLoadedComponent;
};
export type inferSupportedIntegrations<TKind extends WidgetKind> = (WidgetImports[TKind]["definition"] extends {
supportedIntegrations: string[];
}
? WidgetImports[TKind]["definition"]["supportedIntegrations"]
: string[])[number];
export type inferSupportedIntegrationsStrict<TKind extends WidgetKind> = (WidgetImports[TKind]["definition"] extends {
supportedIntegrations: IntegrationKind[];
}
? WidgetImports[TKind]["definition"]["supportedIntegrations"]
: never[])[number];
export type {
inferSupportedIntegrations,
inferSupportedIntegrationsStrict,
WidgetImportKey,
WidgetImports,
} from "./registry";
@@ -1,6 +1,5 @@
import { IconReportSearch, IconServerOff, IconTestPipe } from "@tabler/icons-react";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { createWidgetDefinition } from "../definition";
import { optionsBuilder } from "../options";
@@ -28,9 +27,7 @@ export const { definition, componentLoader } = createWidgetDefinition("indexerMa
},
},
],
refetchInterval: null,
createOptions,
supportedIntegrations: getIntegrationKindsByCategory("indexerManager"),
errors: {
INTERNAL_SERVER_ERROR: {
icon: IconServerOff,
+4 -3
View File
@@ -1,7 +1,7 @@
import type { QueryKey } from "@tanstack/react-query";
import { describe, expect, it } from "vitest";
import { widgetIntegrationSupport, widgetKinds as definedWidgetKinds } from "@homarr/definitions";
import { widgetIntegrationSupport, widgetKinds as declaredWidgetKinds } from "@homarr/definitions";
import {
createRetryableLoader,
@@ -58,7 +58,7 @@ describe("widget manifest promise stability", () => {
});
it("covers every declared widget kind", () => {
expect(new Set(widgetKinds)).toEqual(new Set(definedWidgetKinds));
expect(new Set(widgetKinds)).toEqual(new Set(declaredWidgetKinds));
});
it("loads matching definitions and component loaders for every widget", async () => {
@@ -98,7 +98,8 @@ describe("widget manifest promise stability", () => {
const definition = definitions.get(kind);
const supportedIntegrations =
definition && "supportedIntegrations" in definition ? (definition.supportedIntegrations ?? []) : [];
expect([...(widgetIntegrationSupport[kind] ?? [])].toSorted()).toEqual([...supportedIntegrations].toSorted());
const expectedIntegrations = widgetIntegrationSupport[kind] ?? [];
expect(expectedIntegrations.toSorted()).toEqual([...supportedIntegrations].toSorted());
}
});
+29 -141
View File
@@ -2,156 +2,30 @@ import type { ComponentType } from "react";
import { objectEntries } from "@homarr/common";
import type { WidgetKind } from "@homarr/definitions";
import { widgetKinds as declaredWidgetKinds } from "@homarr/definitions";
import type { SettingsContextProps } from "@homarr/settings/creator";
import type { WidgetComponentProps, WidgetDefinition } from "./definition";
import type { WidgetOptionDefinition } from "./options";
type WidgetModule = {
definition: WidgetDefinition;
componentLoader: () => Promise<{ default: ComponentType<WidgetComponentProps<WidgetKind>> }>;
};
import { widgetModuleLoaders } from "./registry";
type WidgetComponentModule = {
default: ComponentType<WidgetComponentProps<WidgetKind>>;
};
type WidgetModule = {
definition: WidgetDefinition;
componentLoader: () => Promise<WidgetComponentModule>;
};
export type WidgetResources = {
definition: WidgetDefinition;
Component: ComponentType<WidgetComponentProps<WidgetKind>>;
};
const moduleLoaders: Record<WidgetKind, () => Promise<WidgetModule>> = {
clock: () => import("./clock") as Promise<WidgetModule>,
weather: () => import("./weather") as Promise<WidgetModule>,
airQuality: () => import("./air-quality") as Promise<WidgetModule>,
countdown: () => import("./countdown") as Promise<WidgetModule>,
timer: () => import("./timer") as Promise<WidgetModule>,
app: () => import("./app") as Promise<WidgetModule>,
assistant: () => import("./assistant") as Promise<WidgetModule>,
archiveTeamWarrior: () => import("./archive-team-warrior") as Promise<WidgetModule>,
anchorNote: () => import("./anchor-note") as Promise<WidgetModule>,
notebook: () => import("./notebook") as Promise<WidgetModule>,
iframe: () => import("./iframe") as Promise<WidgetModule>,
video: () => import("./video") as Promise<WidgetModule>,
dnsHoleSummary: () => import("./dns-hole/summary") as Promise<WidgetModule>,
dnsHoleControls: () => import("./dns-hole/controls") as Promise<WidgetModule>,
"smartHome-entityState": () => import("./smart-home/entity-state") as Promise<WidgetModule>,
"smartHome-executeAutomation": () => import("./smart-home/execute-automation") as Promise<WidgetModule>,
stockPrice: () => import("./stocks") as Promise<WidgetModule>,
mediaServer: () => import("./media-server") as Promise<WidgetModule>,
calendar: () => import("./calendar") as Promise<WidgetModule>,
downloads: () => import("./downloads") as Promise<WidgetModule>,
"mediaRequests-requestList": () => import("./media-requests/list") as Promise<WidgetModule>,
"mediaRequests-requestStats": () => import("./media-requests/stats") as Promise<WidgetModule>,
mediaMissing: () => import("./media-missing") as Promise<WidgetModule>,
networkControllerSummary: () => import("./network-controller/summary") as Promise<WidgetModule>,
networkControllerStatus: () => import("./network-controller/network-status") as Promise<WidgetModule>,
rssFeed: () => import("./rssFeed") as Promise<WidgetModule>,
bookmarks: () => import("./bookmarks") as Promise<WidgetModule>,
bazarr: () => import("./bazarr") as Promise<WidgetModule>,
indexerManager: () => import("./indexer-manager") as Promise<WidgetModule>,
healthMonitoring: () => import("./health-monitoring") as Promise<WidgetModule>,
mediaTranscoding: () => import("./media-transcoding") as Promise<WidgetModule>,
minecraftServerStatus: () => import("./minecraft/server-status") as Promise<WidgetModule>,
dockerContainers: () => import("./docker") as Promise<WidgetModule>,
releases: () => import("./releases") as Promise<WidgetModule>,
firewall: () => import("./firewall") as Promise<WidgetModule>,
notifications: () => import("./notifications") as Promise<WidgetModule>,
mediaReleases: () => import("./media-releases") as Promise<WidgetModule>,
systemResources: () => import("./system-resources") as Promise<WidgetModule>,
coolify: () => import("./coolify") as Promise<WidgetModule>,
systemDisks: () => import("./system-disks") as Promise<WidgetModule>,
timetable: () => import("./timetable") as Promise<WidgetModule>,
"immich-serverStats": () => import("./immich/server-stats") as Promise<WidgetModule>,
"immich-albumCarousel": () => import("./immich/album-carousel") as Promise<WidgetModule>,
paperlessNgx: () => import("./paperless-ngx") as Promise<WidgetModule>,
patchmon: () => import("./patchmon") as Promise<WidgetModule>,
tracearr: () => import("./tracearr") as Promise<WidgetModule>,
speedtestTracker: () => import("./speedtest-tracker") as Promise<WidgetModule>,
uptimeKuma: () => import("./uptime-kuma") as Promise<WidgetModule>,
audioStats: () => import("./audio-stats") as Promise<WidgetModule>,
umami: () => import("./umami") as Promise<WidgetModule>,
vpn: () => import("./vpn") as Promise<WidgetModule>,
ups: () => import("./ups") as Promise<WidgetModule>,
beszelSystemTable: () => import("./beszel-system-table") as Promise<WidgetModule>,
beszelSystemGrid: () => import("./beszel-system-grid") as Promise<WidgetModule>,
beszelAlerts: () => import("./beszel-alerts") as Promise<WidgetModule>,
beszelSystemStats: () => import("./beszel-system-stats") as Promise<WidgetModule>,
traefik: () => import("./traefik") as Promise<WidgetModule>,
customApi: () => import("./custom-api") as Promise<WidgetModule>,
wud: () => import("./wud") as Promise<WidgetModule>,
};
// Keep these imports explicit so Turbopack can create one discoverable chunk per
// widget implementation. Loading this registry does not load the implementations.
const componentLoaders: Record<WidgetKind, () => Promise<WidgetComponentModule>> = {
clock: () => import("./clock/component") as Promise<WidgetComponentModule>,
weather: () => import("./weather/component") as Promise<WidgetComponentModule>,
airQuality: () => import("./air-quality/component") as Promise<WidgetComponentModule>,
countdown: () => import("./countdown/component") as Promise<WidgetComponentModule>,
timer: () => import("./timer/component") as Promise<WidgetComponentModule>,
app: () => import("./app/component") as Promise<WidgetComponentModule>,
assistant: () => import("./assistant/component") as Promise<WidgetComponentModule>,
archiveTeamWarrior: () => import("./archive-team-warrior/component") as Promise<WidgetComponentModule>,
anchorNote: () => import("./anchor-note/component") as Promise<WidgetComponentModule>,
notebook: () => import("./notebook/component") as Promise<WidgetComponentModule>,
iframe: () => import("./iframe/component") as Promise<WidgetComponentModule>,
video: () => import("./video/component") as Promise<WidgetComponentModule>,
dnsHoleSummary: () => import("./dns-hole/summary/component") as Promise<WidgetComponentModule>,
dnsHoleControls: () => import("./dns-hole/controls/component") as Promise<WidgetComponentModule>,
"smartHome-entityState": () => import("./smart-home/entity-state/component") as Promise<WidgetComponentModule>,
"smartHome-executeAutomation": () =>
import("./smart-home/execute-automation/component") as Promise<WidgetComponentModule>,
stockPrice: () => import("./stocks/component") as Promise<WidgetComponentModule>,
mediaServer: () => import("./media-server/component") as Promise<WidgetComponentModule>,
calendar: () => import("./calendar/component") as Promise<WidgetComponentModule>,
downloads: () => import("./downloads/component") as Promise<WidgetComponentModule>,
"mediaRequests-requestList": () => import("./media-requests/list/component") as Promise<WidgetComponentModule>,
"mediaRequests-requestStats": () => import("./media-requests/stats/component") as Promise<WidgetComponentModule>,
mediaMissing: () => import("./media-missing/component") as Promise<WidgetComponentModule>,
networkControllerSummary: () => import("./network-controller/summary/component") as Promise<WidgetComponentModule>,
networkControllerStatus: () =>
import("./network-controller/network-status/component") as Promise<WidgetComponentModule>,
rssFeed: () => import("./rssFeed/component") as Promise<WidgetComponentModule>,
bookmarks: () => import("./bookmarks/component") as Promise<WidgetComponentModule>,
bazarr: () => import("./bazarr/component") as Promise<WidgetComponentModule>,
indexerManager: () => import("./indexer-manager/component") as Promise<WidgetComponentModule>,
healthMonitoring: () => import("./health-monitoring/component") as Promise<WidgetComponentModule>,
mediaTranscoding: () => import("./media-transcoding/component") as Promise<WidgetComponentModule>,
minecraftServerStatus: () => import("./minecraft/server-status/component") as Promise<WidgetComponentModule>,
dockerContainers: () => import("./docker/component") as Promise<WidgetComponentModule>,
releases: () => import("./releases/component") as Promise<WidgetComponentModule>,
firewall: () => import("./firewall/component") as Promise<WidgetComponentModule>,
notifications: () => import("./notifications/component") as Promise<WidgetComponentModule>,
mediaReleases: () => import("./media-releases/component") as Promise<WidgetComponentModule>,
systemResources: () => import("./system-resources/component") as Promise<WidgetComponentModule>,
coolify: () => import("./coolify/component") as Promise<WidgetComponentModule>,
systemDisks: () => import("./system-disks/component") as Promise<WidgetComponentModule>,
timetable: () => import("./timetable/component") as Promise<WidgetComponentModule>,
"immich-serverStats": () => import("./immich/server-stats/component") as Promise<WidgetComponentModule>,
"immich-albumCarousel": () => import("./immich/album-carousel/component") as Promise<WidgetComponentModule>,
paperlessNgx: () => import("./paperless-ngx/component") as Promise<WidgetComponentModule>,
patchmon: () => import("./patchmon/component") as Promise<WidgetComponentModule>,
tracearr: () => import("./tracearr/component") as Promise<WidgetComponentModule>,
speedtestTracker: () => import("./speedtest-tracker/component") as Promise<WidgetComponentModule>,
uptimeKuma: () => import("./uptime-kuma/component") as Promise<WidgetComponentModule>,
audioStats: () => import("./audio-stats/component") as Promise<WidgetComponentModule>,
umami: () => import("./umami/component") as Promise<WidgetComponentModule>,
vpn: () => import("./vpn/component") as Promise<WidgetComponentModule>,
ups: () => import("./ups/component") as Promise<WidgetComponentModule>,
beszelSystemTable: () => import("./beszel-system-table/component") as Promise<WidgetComponentModule>,
beszelSystemGrid: () => import("./beszel-system-grid/component") as Promise<WidgetComponentModule>,
beszelAlerts: () => import("./beszel-alerts/component") as Promise<WidgetComponentModule>,
beszelSystemStats: () => import("./beszel-system-stats/component") as Promise<WidgetComponentModule>,
traefik: () => import("./traefik/component") as Promise<WidgetComponentModule>,
customApi: () => import("./custom-api/component") as Promise<WidgetComponentModule>,
wud: () => import("./wud/component") as Promise<WidgetComponentModule>,
};
const definitionPromises = new Map<WidgetKind, Promise<WidgetDefinition>>();
export const widgetKinds = Object.keys(moduleLoaders) as WidgetKind[];
export const widgetKinds = [...declaredWidgetKinds];
export const createRetryableLoader = <TKey, TValue>(loaders: ReadonlyMap<TKey, () => Promise<TValue>>) => {
const promises = new Map<TKey, Promise<TValue>>();
@@ -172,17 +46,29 @@ export const createRetryableLoader = <TKey, TValue>(loaders: ReadonlyMap<TKey, (
};
};
export const loadWidgetModule = createRetryableLoader(
new Map(Object.entries(moduleLoaders) as [WidgetKind, () => Promise<WidgetModule>][]),
const loadRegisteredWidgetModule = createRetryableLoader(
new Map(Object.entries(widgetModuleLoaders) as [WidgetKind, () => Promise<WidgetModule>][]),
);
export const loadWidgetComponent = createRetryableLoader(
new Map(Object.entries(componentLoaders) as [WidgetKind, () => Promise<WidgetComponentModule>][]),
);
export const loadWidgetModule = (kind: WidgetKind) => loadRegisteredWidgetModule(kind);
export const loadWidgetResources = createRetryableLoader(
const loadRegisteredWidgetComponent = createRetryableLoader(
new Map(
(Object.keys(moduleLoaders) as WidgetKind[]).map((kind) => [
widgetKinds.map((kind) => [
kind,
async () => {
const widgetModule = await loadWidgetModule(kind);
return widgetModule.componentLoader();
},
]),
),
);
export const loadWidgetComponent = (kind: WidgetKind) => loadRegisteredWidgetComponent(kind);
const loadRegisteredWidgetResources = createRetryableLoader(
new Map(
widgetKinds.map((kind) => [
kind,
async () => {
const [{ definition }, { default: Component }] = await Promise.all([
@@ -195,6 +81,8 @@ export const loadWidgetResources = createRetryableLoader(
),
);
export const loadWidgetResources = (kind: WidgetKind) => loadRegisteredWidgetResources(kind);
export const loadWidgetDefinition = (kind: WidgetKind) => {
const existing = definitionPromises.get(kind);
if (existing) return existing;
@@ -1,6 +1,5 @@
import { IconMovie } from "@tabler/icons-react";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { createWidgetDefinition, matchesWidgetRuntimeQuery } from "../definition";
import { optionsBuilder } from "../options";
@@ -10,7 +9,6 @@ const pageSizeOptions = ["10", "20", "30", "50"] as const;
export const { componentLoader, definition } = createWidgetDefinition("mediaMissing", {
icon: IconMovie,
supportsAdvancedFocus: true,
queryKey: [["widget", "mediaOrganizer", "getData"]],
queryMatcher: matchesWidgetRuntimeQuery,
createOptions() {
return optionsBuilder.from((factory) => ({
@@ -25,5 +23,4 @@ export const { componentLoader, definition } = createWidgetDefinition("mediaMiss
}),
}));
},
supportedIntegrations: getIntegrationKindsByCategory("mediaOrganizer"),
}).withDynamicImport(() => import("./component"));
@@ -6,8 +6,6 @@ import { optionsBuilder } from "../options";
export const { definition, componentLoader } = createWidgetDefinition("mediaReleases", {
icon: IconTicket,
supportsAdvancedFocus: true,
queryKey: [["widget", "mediaRelease"]],
refetchInterval: null,
createOptions() {
return optionsBuilder.from((factory) => ({
layout: factory.select({
@@ -34,5 +32,4 @@ export const { definition, componentLoader } = createWidgetDefinition("mediaRele
}),
}));
},
supportedIntegrations: ["mock", "emby", "jellyfin", "plex"],
}).withDynamicImport(() => import("./component"));
@@ -1,7 +1,6 @@
import { IconSearch, IconZoomQuestion } from "@tabler/icons-react";
import { z } from "zod/v4";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { openMediaRequestSearch } from "@homarr/spotlight";
import { createWidgetDefinition, widgetQueryInputMatches } from "../../definition";
@@ -29,7 +28,6 @@ const createOptions = () =>
export const { componentLoader, definition } = createWidgetDefinition("mediaRequests-requestList", {
supportsAdvancedFocus: false,
icon: IconZoomQuestion,
queryKey: [["widget", "mediaRequests", "getLatestRequests"]],
queryMatcher: ({ input }, scope) =>
widgetQueryInputMatches(input, {
integrationIds: scope.integrationIds,
@@ -50,5 +48,4 @@ export const { componentLoader, definition } = createWidgetDefinition("mediaRequ
},
},
],
supportedIntegrations: getIntegrationKindsByCategory("mediaRequest"),
}).withDynamicImport(() => import("./component"));
@@ -1,6 +1,5 @@
import { IconChartBar, IconSearch } from "@tabler/icons-react";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { openMediaRequestSearch } from "@homarr/spotlight";
import { createWidgetDefinition } from "../../definition";
@@ -10,7 +9,6 @@ const createOptions = () => ({});
export const { componentLoader, definition } = createWidgetDefinition("mediaRequests-requestStats", {
supportsAdvancedFocus: false,
icon: IconChartBar,
queryKey: [["widget", "mediaRequests", "getStats"]],
createOptions,
contextActions: ({ integrationIds }) => [
{
@@ -22,5 +20,4 @@ export const { componentLoader, definition } = createWidgetDefinition("mediaRequ
},
},
],
supportedIntegrations: getIntegrationKindsByCategory("mediaRequest"),
}).withDynamicImport(() => import("./component"));
@@ -1,6 +1,5 @@
import { IconVideo } from "@tabler/icons-react";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { createWidgetDefinition, widgetQueryInputMatches } from "../definition";
import { optionsBuilder } from "../options";
@@ -8,13 +7,11 @@ import { optionsBuilder } from "../options";
export const { componentLoader, definition } = createWidgetDefinition("mediaServer", {
icon: IconVideo,
supportsAdvancedFocus: true,
queryKey: [["widget", "mediaServer", "getCurrentStreams"]],
queryMatcher: ({ input }, scope) =>
widgetQueryInputMatches(input, {
integrationIds: scope.integrationIds,
showOnlyPlaying: scope.options.showOnlyPlaying,
}),
refetchInterval: 10,
createOptions() {
return optionsBuilder.from((factory) => ({
showOnlyPlaying: factory.switch({ defaultValue: true, withDescription: true }),
@@ -22,5 +19,4 @@ export const { componentLoader, definition } = createWidgetDefinition("mediaServ
showLocation: factory.switch({ defaultValue: true, withDescription: true }),
}));
},
supportedIntegrations: getIntegrationKindsByCategory("mediaService"),
}).withDynamicImport(() => import("./component"));
@@ -2,7 +2,6 @@ import { IconTransform } from "@tabler/icons-react";
import { z } from "zod/v4";
import { capitalize } from "@homarr/common";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { createWidgetDefinition, matchesWidgetRuntimeQuery } from "../definition";
import { optionsBuilder } from "../options";
@@ -12,10 +11,7 @@ export const views = ["workers", "queue", "statistics"] as const;
export const { componentLoader, definition } = createWidgetDefinition("mediaTranscoding", {
icon: IconTransform,
supportsAdvancedFocus: true,
queryKey: [["widget", "mediaTranscoding", "getDataAsync"]],
queryMatcher: matchesWidgetRuntimeQuery,
maxIntegrations: 1,
refetchInterval: null,
createOptions() {
return optionsBuilder.from((factory) => ({
defaultView: factory.select({
@@ -25,5 +21,4 @@ export const { componentLoader, definition } = createWidgetDefinition("mediaTran
queuePageSize: factory.number({ defaultValue: 10, validate: z.number().min(1).max(30) }),
}));
},
supportedIntegrations: getIntegrationKindsByCategory("mediaTranscoding"),
}).withDynamicImport(() => import("./component"));
@@ -7,14 +7,12 @@ import { optionsBuilder } from "../../options";
export const { componentLoader, definition } = createWidgetDefinition("minecraftServerStatus", {
supportsAdvancedFocus: false,
icon: IconBrandMinecraft,
queryKey: [["widget", "minecraft", "getServerStatus"]],
queryMatcher: ({ input }, scope) =>
widgetQueryInputMatches(input, {
title: scope.options.title,
domain: scope.options.domain,
isBedrockServer: scope.options.isBedrockServer,
}),
refetchInterval: null,
createOptions() {
return optionsBuilder.from((factory) => ({
title: factory.text({ defaultValue: "" }),
@@ -1,6 +1,5 @@
import { IconServerOff, IconTopologyFull } from "@tabler/icons-react";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { createWidgetDefinition } from "../../definition";
import { optionsBuilder } from "../../options";
@@ -8,8 +7,6 @@ import { optionsBuilder } from "../../options";
export const { definition, componentLoader } = createWidgetDefinition("networkControllerStatus", {
icon: IconTopologyFull,
supportsAdvancedFocus: true,
queryKey: [["widget", "networkController"]],
refetchInterval: null,
createOptions() {
return optionsBuilder.from((factory) => ({
content: factory.select({
@@ -21,7 +18,6 @@ export const { definition, componentLoader } = createWidgetDefinition("networkCo
}),
}));
},
supportedIntegrations: getIntegrationKindsByCategory("networkController"),
errors: {
INTERNAL_SERVER_ERROR: {
icon: IconServerOff,
@@ -1,6 +1,5 @@
import { IconServerOff, IconTopologyFull } from "@tabler/icons-react";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { createWidgetDefinition } from "../../definition";
import { optionsBuilder } from "../../options";
@@ -8,12 +7,9 @@ import { optionsBuilder } from "../../options";
export const { definition, componentLoader } = createWidgetDefinition("networkControllerSummary", {
supportsAdvancedFocus: true,
icon: IconTopologyFull,
queryKey: [["widget", "networkController"]],
refetchInterval: null,
createOptions() {
return optionsBuilder.from(() => ({}));
},
supportedIntegrations: getIntegrationKindsByCategory("networkController"),
errors: {
INTERNAL_SERVER_ERROR: {
icon: IconServerOff,
@@ -1,6 +1,5 @@
import { IconMessage } from "@tabler/icons-react";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { createWidgetDefinition, widgetQueryInputMatches } from "../definition";
import { optionsBuilder } from "../options";
@@ -8,7 +7,6 @@ import { optionsBuilder } from "../options";
export const { componentLoader, definition } = createWidgetDefinition("notifications", {
supportsAdvancedFocus: true,
icon: IconMessage,
queryKey: [["widget", "notifications", "getNotifications"]],
queryMatcher: ({ input }, scope) =>
widgetQueryInputMatches(input, {
hideLogos: scope.options.hideLogos,
@@ -19,5 +17,4 @@ export const { componentLoader, definition } = createWidgetDefinition("notificat
hideLogos: factory.switch({ defaultValue: false }),
}));
},
supportedIntegrations: getIntegrationKindsByCategory("notifications"),
}).withDynamicImport(() => import("./component"));
@@ -6,10 +6,6 @@ import { optionsBuilder } from "../options";
export const { definition, componentLoader } = createWidgetDefinition("paperlessNgx", {
supportsAdvancedFocus: false,
icon: IconFileText,
refetchInterval: null,
supportedIntegrations: ["paperlessNgx"],
integrationsRequired: true,
maxIntegrations: 1,
createOptions() {
return optionsBuilder.from((factory) => ({
showInboxRatio: factory.switch({
-3
View File
@@ -9,9 +9,6 @@ import { patchmonOptionsSuperRefine } from "./threshold-validation";
export const { definition, componentLoader } = createWidgetDefinition("patchmon", {
supportsAdvancedFocus: true,
icon: IconShieldCheck,
supportedIntegrations: ["patchmon"],
integrationsRequired: true,
maxIntegrations: 1,
createOptions() {
return optionsBuilder.from(
(factory) => ({
+22 -12
View File
@@ -5,17 +5,24 @@ import type { WidgetKind } from "@homarr/definitions";
import { createSettings } from "@homarr/settings/creator";
import { loadWidgetDefinition, reduceWidgetOptionsWithDefinition } from "./manifest";
import prefetchForApps from "./app/prefetch";
import prefetchForBookmarks from "./bookmarks/prefetch";
import type { Prefetch, WidgetOptionsRecordOf } from "./definition";
import type { PrefetchLoader, WidgetOptionsRecordOf } from "./definition";
import type { inferOptionsFromCreator } from "./options";
const prefetchCallbacks: Partial<{
[TKind in WidgetKind]: Prefetch<TKind>;
}> = {
bookmarks: prefetchForBookmarks,
app: prefetchForApps,
};
const definePrefetchLoaders = <TLoaders extends Partial<{ [TKind in WidgetKind]: PrefetchLoader<TKind> }>>(
loaders: TLoaders,
) => loaders;
// Keep these imports explicit so Next.js can trace each optional prefetch
// module without loading its database-specific implementation eagerly.
const prefetchLoaders = definePrefetchLoaders({
app: () => import("./app/prefetch"),
bookmarks: () => import("./bookmarks/prefetch"),
});
type PrefetchWidgetKind = keyof typeof prefetchLoaders;
const hasPrefetchLoader = (kind: WidgetKind): kind is PrefetchWidgetKind =>
Object.prototype.hasOwnProperty.call(prefetchLoaders, kind);
export const prefetchForKindAsync = async <TKind extends WidgetKind>(
kind: TKind,
@@ -25,12 +32,15 @@ export const prefetchForKindAsync = async <TKind extends WidgetKind>(
integrationIds: string[];
}[],
) => {
const callback = prefetchCallbacks[kind];
if (!callback) {
if (!hasPrefetchLoader(kind)) {
return;
}
const [serverSettings, definition] = await Promise.all([getRscServerSettingsAsync(), loadWidgetDefinition(kind)]);
const [{ default: callback }, serverSettings, definition] = await Promise.all([
prefetchLoaders[kind](),
getRscServerSettingsAsync(),
loadWidgetDefinition(kind),
]);
const itemsWithDefaultOptions = items.map((item) => ({
...item,
+59 -36
View File
@@ -1,38 +1,61 @@
import { generatedWidgetOperationPolicies, widgetFeatureCatalog } from "@homarr/definitions";
interface WidgetQueryRefetchInterval {
queryKey: readonly [readonly string[]];
intervalSeconds: number | null;
staleTimeSeconds?: number;
}
const createWidgetQueryRefetchIntervals = (): WidgetQueryRefetchInterval[] => {
const policies = new Map<string, WidgetQueryRefetchInterval>();
for (const descriptor of Object.values(widgetFeatureCatalog)) {
if (!("query" in descriptor) || !("refetchIntervalSeconds" in descriptor.query)) continue;
for (const path of descriptor.query.paths) {
if (path[0] !== "widget" && path[0] !== "docker") continue;
const queryKey = [path] as const;
const serializedQueryKey = JSON.stringify(queryKey);
const intervalSeconds = descriptor.query.refetchIntervalSeconds;
const existing = policies.get(serializedQueryKey);
if (existing && existing.intervalSeconds !== intervalSeconds) {
throw new Error(`Conflicting widget refetch intervals for ${serializedQueryKey}`);
}
policies.set(serializedQueryKey, { queryKey, intervalSeconds });
}
}
for (const policy of generatedWidgetOperationPolicies) {
if (policy.kind !== "query") continue;
if (policy.path[0] !== "widget" && policy.path[0] !== "docker") continue;
const queryKey = [policy.path] as const;
const serializedQueryKey = JSON.stringify(queryKey);
let existing = policies.get(serializedQueryKey);
if (!existing) {
if (policy.refetchIntervalSeconds === undefined) continue;
existing = { queryKey, intervalSeconds: policy.refetchIntervalSeconds };
}
if (
existing.intervalSeconds !== undefined &&
policy.refetchIntervalSeconds !== undefined &&
existing.intervalSeconds !== policy.refetchIntervalSeconds
) {
throw new Error(`Conflicting generated widget refetch interval for ${serializedQueryKey}`);
}
if (policy.refetchIntervalSeconds !== undefined) {
existing.intervalSeconds = policy.refetchIntervalSeconds;
}
if (policy.staleTimeSeconds !== undefined) existing.staleTimeSeconds = policy.staleTimeSeconds;
policies.set(serializedQueryKey, existing);
}
return [...policies.values()];
};
/**
* Query policy used by the root client provider.
*
* Keep this module free of widget component/definition imports. Importing the
* full widget registry from a root provider makes every widget part of the
* initial client graph, even before a board has rendered one widget.
* Query policy used by the root client provider. This derives from the
* server-safe feature catalog and never imports widget definitions or code.
*/
export const widgetQueryRefetchIntervals = [
{ queryKey: [["docker", "getContainers"]], intervalSeconds: 30 },
{ queryKey: [["widget", "dnsHole"]], intervalSeconds: 10 },
{ queryKey: [["widget", "downloads", "getJobsAndStatuses"]], intervalSeconds: 10 },
{ queryKey: [["widget", "firewall"]], intervalSeconds: 10 },
{ queryKey: [["widget", "healthMonitoring"]], intervalSeconds: 10 },
{ queryKey: [["widget", "mediaServer", "getCurrentStreams"]], intervalSeconds: 10 },
{ queryKey: [["widget", "tracearr"]], intervalSeconds: 10 },
{ queryKey: [["widget", "weather", "atLocation"]], intervalSeconds: 600 },
{ queryKey: [["widget", "airQuality", "atLocation"]], intervalSeconds: 900 },
{ queryKey: [["widget", "immich", "getAlbum"]], intervalSeconds: null },
{ queryKey: [["widget", "immich", "getServerStats"]], intervalSeconds: null },
{ queryKey: [["widget", "immich", "getAlbums"]], intervalSeconds: null },
{ queryKey: [["widget", "indexerManager"]], intervalSeconds: null },
{ queryKey: [["widget", "mediaRelease"]], intervalSeconds: null },
{ queryKey: [["widget", "mediaTranscoding", "getDataAsync"]], intervalSeconds: null },
{ queryKey: [["widget", "minecraft", "getServerStatus"]], intervalSeconds: null },
{ queryKey: [["widget", "networkController"]], intervalSeconds: null },
{ queryKey: [["widget", "paperlessNgx"]], intervalSeconds: null },
{ queryKey: [["widget", "releases", "getLatest"]], intervalSeconds: null },
{ queryKey: [["widget", "rssFeed", "getFeeds"]], intervalSeconds: null },
{ queryKey: [["widget", "speedtestTracker"]], intervalSeconds: null },
{ queryKey: [["widget", "stockPrice", "getPriceHistory"]], intervalSeconds: null },
{ queryKey: [["widget", "umami", "getVisitorStats"]], intervalSeconds: null },
{ queryKey: [["widget", "umami", "getActiveVisitors"]], intervalSeconds: null },
{ queryKey: [["widget", "umami", "getMultiEventTimeSeries"]], intervalSeconds: null },
{ queryKey: [["widget", "umami", "getTopPages"]], intervalSeconds: null },
{ queryKey: [["widget", "umami", "getTopReferrers"]], intervalSeconds: null },
{ queryKey: [["widget", "vpn"]], intervalSeconds: null },
{ queryKey: [["widget", "wud"]], intervalSeconds: null },
] as const;
export const widgetQueryRefetchIntervals = createWidgetQueryRefetchIntervals();
+203
View File
@@ -0,0 +1,203 @@
import type { IntegrationKind, WidgetKind } from "@homarr/definitions";
import type * as airQuality from "./air-quality";
import type * as anchorNote from "./anchor-note";
import type * as app from "./app";
import type * as archiveTeamWarrior from "./archive-team-warrior";
import type * as assistant from "./assistant";
import type * as audioStats from "./audio-stats";
import type * as bazarr from "./bazarr";
import type * as beszelAlerts from "./beszel-alerts";
import type * as beszelSystemGrid from "./beszel-system-grid";
import type * as beszelSystemStats from "./beszel-system-stats";
import type * as beszelSystemTable from "./beszel-system-table";
import type * as bookmarks from "./bookmarks";
import type * as calendar from "./calendar";
import type * as clock from "./clock";
import type * as coolify from "./coolify";
import type * as countdown from "./countdown";
import type * as customApi from "./custom-api";
import type * as dnsHoleControls from "./dns-hole/controls";
import type * as dnsHoleSummary from "./dns-hole/summary";
import type * as dockerContainers from "./docker";
import type * as firewall from "./firewall";
import type * as healthMonitoring from "./health-monitoring";
import type * as iframe from "./iframe";
import type * as immichAlbumCarousel from "./immich/album-carousel";
import type * as immichServerStats from "./immich/server-stats";
import type * as indexerManager from "./indexer-manager";
import type * as mediaMissing from "./media-missing";
import type * as mediaReleases from "./media-releases";
import type * as mediaRequestsList from "./media-requests/list";
import type * as mediaRequestsStats from "./media-requests/stats";
import type * as mediaServer from "./media-server";
import type * as mediaTranscoding from "./media-transcoding";
import type * as minecraftServerStatus from "./minecraft/server-status";
import type * as networkControllerStatus from "./network-controller/network-status";
import type * as networkControllerSummary from "./network-controller/summary";
import type * as notebook from "./notebook";
import type * as notifications from "./notifications";
import type * as paperlessNgx from "./paperless-ngx";
import type * as patchmon from "./patchmon";
import type * as releases from "./releases";
import type * as rssFeed from "./rssFeed";
import type * as smartHomeEntityState from "./smart-home/entity-state";
import type * as smartHomeExecuteAutomation from "./smart-home/execute-automation";
import type * as speedtestTracker from "./speedtest-tracker";
import type * as stockPrice from "./stocks";
import type * as systemDisks from "./system-disks";
import type * as systemResources from "./system-resources";
import type * as timetable from "./timetable";
import type * as timer from "./timer";
import type * as tracearr from "./tracearr";
import type * as traefik from "./traefik";
import type * as umami from "./umami";
import type * as ups from "./ups";
import type * as uptimeKuma from "./uptime-kuma";
import type * as video from "./video";
import type * as vpn from "./vpn";
import type * as wud from "./wud";
import { generatedWidgetModuleLoaders } from "./generated/widget-modules";
import type { GeneratedWidgetImports } from "./generated/widget-modules";
type WidgetModule = {
definition: unknown;
componentLoader: () => Promise<unknown>;
};
// Keep these imports explicit so Next.js and Turbopack can discover every widget
// module without loading any widget definition or component eagerly.
export const widgetModuleLoaders = {
clock: () => import("./clock"),
airQuality: () => import("./air-quality"),
countdown: () => import("./countdown"),
timer: () => import("./timer"),
app: () => import("./app"),
assistant: () => import("./assistant"),
archiveTeamWarrior: () => import("./archive-team-warrior"),
anchorNote: () => import("./anchor-note"),
notebook: () => import("./notebook"),
iframe: () => import("./iframe"),
video: () => import("./video"),
dnsHoleSummary: () => import("./dns-hole/summary"),
dnsHoleControls: () => import("./dns-hole/controls"),
"smartHome-entityState": () => import("./smart-home/entity-state"),
"smartHome-executeAutomation": () => import("./smart-home/execute-automation"),
stockPrice: () => import("./stocks"),
mediaServer: () => import("./media-server"),
calendar: () => import("./calendar"),
"mediaRequests-requestList": () => import("./media-requests/list"),
"mediaRequests-requestStats": () => import("./media-requests/stats"),
mediaMissing: () => import("./media-missing"),
networkControllerSummary: () => import("./network-controller/summary"),
networkControllerStatus: () => import("./network-controller/network-status"),
rssFeed: () => import("./rssFeed"),
bookmarks: () => import("./bookmarks"),
bazarr: () => import("./bazarr"),
indexerManager: () => import("./indexer-manager"),
healthMonitoring: () => import("./health-monitoring"),
mediaTranscoding: () => import("./media-transcoding"),
minecraftServerStatus: () => import("./minecraft/server-status"),
dockerContainers: () => import("./docker"),
releases: () => import("./releases"),
firewall: () => import("./firewall"),
notifications: () => import("./notifications"),
mediaReleases: () => import("./media-releases"),
systemResources: () => import("./system-resources"),
coolify: () => import("./coolify"),
systemDisks: () => import("./system-disks"),
timetable: () => import("./timetable"),
"immich-serverStats": () => import("./immich/server-stats"),
"immich-albumCarousel": () => import("./immich/album-carousel"),
paperlessNgx: () => import("./paperless-ngx"),
patchmon: () => import("./patchmon"),
tracearr: () => import("./tracearr"),
speedtestTracker: () => import("./speedtest-tracker"),
uptimeKuma: () => import("./uptime-kuma"),
audioStats: () => import("./audio-stats"),
umami: () => import("./umami"),
vpn: () => import("./vpn"),
ups: () => import("./ups"),
beszelSystemTable: () => import("./beszel-system-table"),
beszelSystemGrid: () => import("./beszel-system-grid"),
beszelAlerts: () => import("./beszel-alerts"),
beszelSystemStats: () => import("./beszel-system-stats"),
traefik: () => import("./traefik"),
customApi: () => import("./custom-api"),
wud: () => import("./wud"),
...generatedWidgetModuleLoaders,
} satisfies Record<WidgetKind, () => Promise<WidgetModule>>;
export type WidgetImports = {
clock: typeof clock;
airQuality: typeof airQuality;
countdown: typeof countdown;
timer: typeof timer;
app: typeof app;
assistant: typeof assistant;
archiveTeamWarrior: typeof archiveTeamWarrior;
anchorNote: typeof anchorNote;
notebook: typeof notebook;
iframe: typeof iframe;
video: typeof video;
dnsHoleSummary: typeof dnsHoleSummary;
dnsHoleControls: typeof dnsHoleControls;
"smartHome-entityState": typeof smartHomeEntityState;
"smartHome-executeAutomation": typeof smartHomeExecuteAutomation;
stockPrice: typeof stockPrice;
mediaServer: typeof mediaServer;
calendar: typeof calendar;
"mediaRequests-requestList": typeof mediaRequestsList;
"mediaRequests-requestStats": typeof mediaRequestsStats;
mediaMissing: typeof mediaMissing;
networkControllerSummary: typeof networkControllerSummary;
networkControllerStatus: typeof networkControllerStatus;
rssFeed: typeof rssFeed;
bookmarks: typeof bookmarks;
bazarr: typeof bazarr;
indexerManager: typeof indexerManager;
healthMonitoring: typeof healthMonitoring;
mediaTranscoding: typeof mediaTranscoding;
minecraftServerStatus: typeof minecraftServerStatus;
dockerContainers: typeof dockerContainers;
releases: typeof releases;
firewall: typeof firewall;
notifications: typeof notifications;
mediaReleases: typeof mediaReleases;
systemResources: typeof systemResources;
coolify: typeof coolify;
systemDisks: typeof systemDisks;
timetable: typeof timetable;
"immich-serverStats": typeof immichServerStats;
"immich-albumCarousel": typeof immichAlbumCarousel;
paperlessNgx: typeof paperlessNgx;
patchmon: typeof patchmon;
tracearr: typeof tracearr;
speedtestTracker: typeof speedtestTracker;
uptimeKuma: typeof uptimeKuma;
audioStats: typeof audioStats;
umami: typeof umami;
vpn: typeof vpn;
ups: typeof ups;
beszelSystemTable: typeof beszelSystemTable;
beszelSystemGrid: typeof beszelSystemGrid;
beszelAlerts: typeof beszelAlerts;
beszelSystemStats: typeof beszelSystemStats;
traefik: typeof traefik;
customApi: typeof customApi;
wud: typeof wud;
} & GeneratedWidgetImports;
export type WidgetImportKey = keyof WidgetImports;
export type inferSupportedIntegrations<TKind extends WidgetKind> = (WidgetImports[TKind]["definition"] extends {
supportedIntegrations: string[];
}
? WidgetImports[TKind]["definition"]["supportedIntegrations"]
: string[])[number];
export type inferSupportedIntegrationsStrict<TKind extends WidgetKind> = (WidgetImports[TKind]["definition"] extends {
supportedIntegrations: IntegrationKind[];
}
? WidgetImports[TKind]["definition"]["supportedIntegrations"]
: never[])[number];
-2
View File
@@ -15,9 +15,7 @@ const relativeDateSchema = z
export const { definition, componentLoader } = createWidgetDefinition("releases", {
supportsAdvancedFocus: true,
icon: IconRocket,
queryKey: [["widget", "releases", "getLatest"]],
queryMatcher: ({ input }, scope) => widgetQueryInputMatches(input, { itemId: scope.itemId }),
refetchInterval: null,
createOptions() {
return optionsBuilder.from((factory) => ({
newReleaseWithin: factory.text({
-2
View File
@@ -13,13 +13,11 @@ import { optionsBuilder } from "../options";
export const { definition, componentLoader } = createWidgetDefinition("rssFeed", {
supportsAdvancedFocus: true,
icon: IconRss,
queryKey: [["widget", "rssFeed", "getFeeds"]],
queryMatcher: ({ input }, scope) =>
widgetQueryInputMatches(input, {
urls: scope.options.feedUrls,
maximumAmountPosts: scope.options.maximumAmountPosts,
}),
refetchInterval: null,
errors: {
BAD_GATEWAY: {
icon: IconServerOff,
@@ -1,6 +1,5 @@
import { IconBinaryTree, IconServerOff } from "@tabler/icons-react";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { createWidgetDefinition } from "../../definition";
import { optionsBuilder } from "../../options";
@@ -8,8 +7,6 @@ import { optionsBuilder } from "../../options";
export const { definition, componentLoader } = createWidgetDefinition("smartHome-entityState", {
icon: IconBinaryTree,
supportsAdvancedFocus: true,
queryKey: [["widget", "smartHome"]],
maxIntegrations: 1,
createOptions() {
return optionsBuilder.from((factory) => ({
entityId: factory.text({
@@ -22,7 +19,6 @@ export const { definition, componentLoader } = createWidgetDefinition("smartHome
clickable: factory.switch(),
}));
},
supportedIntegrations: getIntegrationKindsByCategory("smartHomeServer"),
errors: {
INTERNAL_SERVER_ERROR: {
icon: IconServerOff,
@@ -1,6 +1,5 @@
import { IconBinaryTree } from "@tabler/icons-react";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { createWidgetDefinition } from "../../definition";
import { optionsBuilder } from "../../options";
@@ -8,12 +7,10 @@ import { optionsBuilder } from "../../options";
export const { definition, componentLoader } = createWidgetDefinition("smartHome-executeAutomation", {
icon: IconBinaryTree,
supportsAdvancedFocus: true,
maxIntegrations: 1,
createOptions() {
return optionsBuilder.from((factory) => ({
displayName: factory.text(),
automationId: factory.text(),
}));
},
supportedIntegrations: getIntegrationKindsByCategory("smartHomeServer"),
}).withDynamicImport(() => import("./component"));
@@ -6,7 +6,6 @@ import { optionsBuilder } from "../options";
export const { definition, componentLoader } = createWidgetDefinition("speedtestTracker", {
icon: IconSpeedboat,
supportsAdvancedFocus: true,
refetchInterval: null,
createOptions() {
return optionsBuilder.from(
(factory) => ({
@@ -30,7 +29,6 @@ export const { definition, componentLoader } = createWidgetDefinition("speedtest
},
);
},
supportedIntegrations: ["speedtestTracker"],
errors: {
INTERNAL_SERVER_ERROR: {
icon: IconServerOff,
-2
View File
@@ -14,14 +14,12 @@ const timeIntervalOptions = stockPriceTimeFrames.interval;
export const { definition, componentLoader } = createWidgetDefinition("stockPrice", {
supportsAdvancedFocus: true,
icon: IconBuildingBank,
queryKey: [["widget", "stockPrice", "getPriceHistory"]],
queryMatcher: ({ input }, scope) =>
widgetQueryInputMatches(input, {
stock: scope.options.stock,
timeRange: scope.options.timeRange,
timeInterval: scope.options.timeInterval,
}),
refetchInterval: null,
createOptions() {
return optionsBuilder.from((factory) => ({
stock: factory.text({
@@ -7,9 +7,6 @@ import { createStorageVolumeMultiSelectOptions } from "../storage-volume-options
export const { definition, componentLoader } = createWidgetDefinition("systemDisks", {
supportsAdvancedFocus: true,
icon: IconServer2,
queryKey: [["widget", "healthMonitoring"]],
refetchInterval: 10,
supportedIntegrations: ["dashDot", "openmediavault", "truenas", "unraid", "synology"],
createOptions() {
return optionsBuilder.from(
(factory) => ({
@@ -22,9 +22,6 @@ const getChartOptionLabel = (key: "cpu" | "memory" | "gpu" | "network", t: (key:
export const { definition, componentLoader } = createWidgetDefinition("systemResources", {
icon: IconGraphFilled,
supportsAdvancedFocus: true,
queryKey: [["widget", "healthMonitoring"]],
refetchInterval: 10,
supportedIntegrations: ["dashDot", "openmediavault", "truenas", "unraid", "glances", "synology"],
createOptions() {
return optionsBuilder.from((factory) => ({
hasShadow: factory.switch({ defaultValue: true }),
-2
View File
@@ -6,7 +6,6 @@ import { optionsBuilder } from "../options";
export const { definition, componentLoader } = createWidgetDefinition("tracearr", {
icon: IconActivityHeartbeat,
supportsAdvancedFocus: true,
refetchInterval: 10,
createOptions() {
return optionsBuilder.from((factory) => ({
showStreams: factory.switch({
@@ -24,7 +23,6 @@ export const { definition, componentLoader } = createWidgetDefinition("tracearr"
}),
}));
},
supportedIntegrations: ["tracearr"],
errors: {
INTERNAL_SERVER_ERROR: {
icon: IconServerOff,
-1
View File
@@ -19,7 +19,6 @@ export const { definition, componentLoader } = createWidgetDefinition("traefik",
}),
}));
},
supportedIntegrations: ["traefik"],
errors: {
INTERNAL_SERVER_ERROR: {
icon: IconRouteOff,
-11
View File
@@ -9,18 +9,7 @@ export const timeFrameValues = ["today", "24h", "7d", "30d", "month", "lastMonth
export const { definition, componentLoader } = createWidgetDefinition("umami", {
icon: IconChartBar,
supportsAdvancedFocus: true,
queryKeys: [
[["widget", "umami", "getVisitorStats"]],
[["widget", "umami", "getActiveVisitors"]],
[["widget", "umami", "getMultiEventTimeSeries"]],
[["widget", "umami", "getTopPages"]],
[["widget", "umami", "getTopReferrers"]],
],
queryMatcher: matchesWidgetRuntimeQuery,
refetchInterval: null,
supportedIntegrations: ["umami"],
integrationsRequired: true,
maxIntegrations: 1,
createOptions() {
return optionsBuilder.from(
(factory) => ({
-2
View File
@@ -1,6 +1,5 @@
import { IconBatteryCharging, IconBatteryOff } from "@tabler/icons-react";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { createWidgetDefinition } from "../definition";
import { optionsBuilder } from "../options";
@@ -21,7 +20,6 @@ export const { definition, componentLoader } = createWidgetDefinition("ups", {
}),
}));
},
supportedIntegrations: getIntegrationKindsByCategory("ups"),
errors: {
INTERNAL_SERVER_ERROR: {
icon: IconBatteryOff,
@@ -34,7 +34,6 @@ export const { definition, componentLoader } = createWidgetDefinition("uptimeKum
}),
}));
},
supportedIntegrations: ["uptimeKuma"],
errors: {
INTERNAL_SERVER_ERROR: {
icon: IconServerOff,
-3
View File
@@ -1,6 +1,5 @@
import { IconShieldLock } from "@tabler/icons-react";
import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { createWidgetDefinition } from "../definition";
import { optionsBuilder } from "../options";
@@ -8,9 +7,7 @@ import { optionsBuilder } from "../options";
export const { componentLoader, definition } = createWidgetDefinition("vpn", {
supportsAdvancedFocus: false,
icon: IconShieldLock,
refetchInterval: null,
createOptions() {
return optionsBuilder.from(() => ({}));
},
supportedIntegrations: getIntegrationKindsByCategory("vpn"),
}).withDynamicImport(() => import("./component"));
Binary file not shown.

After

Width:  |  Height:  |  Size: 23 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.2 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 8.1 KiB

@@ -0,0 +1,50 @@
---
title: "Weather"
description: "Displays the current weather information of a set location."
hide_title: true
---
import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
import { AddingWidget } from "@site/src/components/widgets/adding";
import { WidgetConfig } from "@site/src/components/widgets/configuration";
import { WidgetHeader } from "@site/src/components/widgets/header";
import { weatherWidget } from ".";
<WidgetHeader widget={weatherWidget} categories={["Weather"]} />
The Weather Widget displays current conditions and a responsive forecast for a selected location. New widgets start
with the city and a three-day forecast visible. As the widget gets smaller, it keeps the current condition and
temperature readable before removing secondary details or forecast days.
Select a forecast day to inspect precipitation, apparent temperature, humidity, wind, UV index, sunrise, sunset and
daylight duration with a mouse, keyboard or touch. Open the advanced view for a current-condition summary, a 24-hour
temperature and precipitation chart, and the complete seven-day forecast. The chart has an equivalent data table for
assistive technologies.
The **Show humidity** option controls humidity across the compact current-conditions view, advanced summary, hourly
details, and daily forecast details. Forecast cards use a roomier adaptive grid in advanced view, with four columns on
the standard desktop surface and fewer columns as the surface narrows.
Weather icons are static by default. Animation can be enabled in the widget configuration, but the operating system's
reduced-motion preference always disables it.
<WidgetInteractionGuide />
### Adding the widget
<AddingWidget />
### Configuration
<WidgetConfig configuration={weatherWidget.configuration} />
### Data source
We use the Open Meteo API to fetch the weather and locations. Active weather data refreshes every ten minutes, while
identical location requests can reuse a server response for five minutes. A manual refresh may therefore return the
same still-current server response. If a refresh fails, Homarr keeps the last successful data visible and shows an
error indicator.
Set `NO_EXTERNAL_CONNECTION=true` to disable this and other internet-backed requests.
If you need to whitelist the api, please use the following URL: `https://open-meteo.com`
@@ -0,0 +1,96 @@
import { WidgetDefinition } from "@site/src/types";
import { IconCloud } from "@tabler/icons-react";
export const weatherWidget: WidgetDefinition = {
icon: IconCloud,
name: "Weather",
description: "Displays the current weather information of a set location.",
path: "../../widgets/weather",
configuration: {
items: [
{
name: "Temperature in Fahrenheit",
description: "Display temperature in Fahrenheit instead of Celsius",
values: { type: "boolean" },
defaultValue: "no",
},
{
name: "Disable temperature decimals",
description: "Show temperature as full number",
values: {
type: "boolean",
},
defaultValue: "no",
},
{
name: "Show current wind speed",
description: "Display current wind speed, only for current weather",
values: {
type: "boolean",
},
defaultValue: "no",
},
{
name: "Show humidity",
description: "Display humidity in current conditions, hourly details, and daily forecasts",
values: {
type: "boolean",
},
defaultValue: "yes",
},
{
name: "Animate weather icons",
description: "Animate condition icons unless the operating system requests reduced motion",
values: {
type: "boolean",
},
defaultValue: "no",
},
{
name: "Use imperial speed units",
description: "Display wind speed in mph instead of km/h",
values: {
type: "boolean",
},
defaultValue: "no",
},
{
name: "Weather location",
description: "Location for which to display the weather information",
values: "Select location through search or longitude/latitude",
defaultValue: "Paris / 48.85341, 2.3488",
},
{
name: "Date format",
description: "Format for displaying the date in the widget",
values: {
type: "select",
options: ["dddd, MMMM D", "dddd, D MMMM", "MMM D", "D MMM", "DD/MM/YYYY", "MM/DD/YYYY", "DD/MM", "MM/DD"],
},
defaultValue: "dddd, MMMM D",
},
{
name: "Show city",
description: "Display the city name in the widget",
values: {
type: "boolean",
},
defaultValue: "yes",
},
{
name: "Has forecast",
description: "Display a forecast for the next few days",
values: {
type: "boolean",
},
defaultValue: "yes",
},
{
name: "Amount of forecast days",
description: "Number of days to show in the forecast",
values: "1-7",
defaultValue: "3",
},
],
},
};
+2 -4
View File
@@ -1,15 +1,13 @@
import { IconCloud } from "@tabler/icons-react";
import dayjs from "dayjs";
import { z } from "zod/v4";
import { createWidgetDefinition, widgetQueryInputMatches } from "../definition";
import { optionsBuilder } from "../options";
import { widgetIcon } from "./module.generated";
export const { definition, componentLoader } = createWidgetDefinition("weather", {
icon: IconCloud,
icon: widgetIcon,
supportsAdvancedFocus: true,
queryKey: [["widget", "weather", "atLocation"]],
refetchInterval: 600,
queryMatcher: ({ input }, scope) => {
const location = scope.options.location;
if (location === null || typeof location !== "object" || !("latitude" in location) || !("longitude" in location)) {
@@ -0,0 +1,3 @@
// This file is generated by pnpm widgets:sync. Do not edit it directly.
export { IconCloud as widgetIcon } from "@tabler/icons-react";
+36
View File
@@ -0,0 +1,36 @@
import { defineWidgetModule } from "@homarr/definitions";
export default defineWidgetModule({
kind: "weather",
icon: "IconCloud",
clientEntry: ".",
documentation: {
slug: "weather",
sourceDirectory: "docs",
},
defaultSize: { width: 2, height: 1 },
operations: [
{
name: "atLocation",
path: ["widget", "weather", "atLocation"],
client: {
refetchIntervalSeconds: 600,
staleTimeSeconds: 300,
persist: true,
},
serverCache: {
namespace: "weather:at-location",
ttlMs: 5 * 60 * 1000,
scope: "shared",
},
},
],
routers: [
{
namespace: "weather",
module: "./weather",
exportName: "weatherRouter",
additionalWidgetKinds: ["clock"],
},
],
});
-4
View File
@@ -6,10 +6,6 @@ import { optionsBuilder } from "../options";
export const { definition, componentLoader } = createWidgetDefinition("wud", {
icon: IconBrandDocker,
supportsAdvancedFocus: true,
refetchInterval: null,
supportedIntegrations: ["wud"],
integrationsRequired: true,
maxIntegrations: 1,
createOptions() {
return optionsBuilder.from((factory) => ({
showTitle: factory.switch({ defaultValue: true }),
+1 -1
View File
@@ -4,5 +4,5 @@
"tsBuildInfoFile": "node_modules/.cache/tsbuildinfo.json"
},
"include": ["*.ts", "src", "*.tsx"],
"exclude": ["node_modules"]
"exclude": ["node_modules", "src/**/docs/**"]
}