feat: add community marketplace for custom widgets and CSS

Adds a PocketBase-backed marketplace where users can share custom widgets and CSS themes. Includes a Docusaurus storefront with GitHub OAuth login, submission/voting/comments, and a PocketBase SQL view that computes author names, vote counts, and comment counts without fragile hooks. The Next.js app gets a modal browser for one-click install from the marketplace plus clipboard paste-to-import on the custom widgets pages.
2026-06-24 15:24:48 +02:00
1 parent b6b7bea1dd
commit 1fb7e16d42
@@ -11,6 +11,7 @@ import { IconInfoCircle } from "@tabler/icons-react";
 import { useForm } from "@homarr/form";
 import { useI18n, useScopedI18n } from "@homarr/translation/client";

+import { InstallCssFromStoreButton } from "~/components/store-install/install-from-store-buttons";
 import type { Board } from "../../_types";
 import { useSavePartialSettingsMutation } from "./_shared";
 import classes from "./customcss.module.css";
@@ -45,7 +46,8 @@ export const CustomCssSettingsContent = ({ board }: Props) => {
          {customCssT("customClassesAlert.description")}
        </Alert>

-        <Group justify="end">
+        <Group justify="space-between">
+          <InstallCssFromStoreButton onSelect={(css) => form.setFieldValue("customCss", css)} />
          <Button type="submit" loading={isPending}>
            {t("common.action.saveChanges")}
          </Button>
@@ -1,5 +1,6 @@
 "use client";

+import { useEffect, useState } from "react";
 import { Button, Popover, Stack, Text } from "@mantine/core";
 import { useDisclosure } from "@mantine/hooks";
 import { IconCopy, IconSparkles } from "@tabler/icons-react";
@@ -296,8 +297,11 @@ interface CopyAiPromptButtonProps {
 export const CopyAiPromptButton = ({ rawResponse, currentConfig }: CopyAiPromptButtonProps) => {
  const t = useScopedI18n("customWidget");
  const [opened, { open, close }] = useDisclosure(false);
+  const [mounted, setMounted] = useState(false);
  const { data: schema, isLoading } = clientApi.customWidget.schema.useQuery();

+  useEffect(() => setMounted(true), []);
+
  const handleCopy = async () => {
    if (!schema) return;
    const prompt = buildAiPrompt(schema, rawResponse, currentConfig);
@@ -317,8 +321,8 @@ export const CopyAiPromptButton = ({ rawResponse, currentConfig }: CopyAiPromptB
          variant="light"
          leftSection={<IconSparkles size={16} />}
          onClick={open}
-          loading={isLoading}
-          disabled={!schema}
+          loading={!mounted || isLoading}
+          disabled={!mounted || isLoading || !schema}
          fullWidth
          size="sm"
        >
@@ -30,9 +30,11 @@ import { useScopedI18n } from "@homarr/translation/client";
 import type {
  CustomWidgetAuthType,
  CustomWidgetDisplayType,
+  CustomWidgetImport,
  CustomWidgetMethod,
  CustomWidgetSecretKind,
 } from "@homarr/validation/custom-widget";
+import { customWidgetImportSchema } from "@homarr/validation/custom-widget";
 import type { displayConfigSchema } from "@homarr/validation/custom-widget";
 import { JsonPathTreePicker } from "@homarr/widgets/_inputs/json-path-tree-picker";

@@ -467,6 +469,36 @@ const serverToFormFieldMap: Record<string, Record<string, string>> = {
  customJsx: { template: "template" },
 };

+const importToFormValues: Record<string, (config: Record<string, unknown>) => Record<string, unknown>> = {
+  singleValue: (c) => ({ jsonPath: c.jsonPath, label: c.label ?? "", unit: c.unit ?? "", valueSize: c.valueSize ?? "lg", labelPosition: c.labelPosition ?? "below" }),
+  keyValue: (c) => ({ mappings: (c.mappings as Array<Record<string, string>>)?.map((m) => ({ label: m.label, jsonPath: m.jsonPath, unit: m.unit ?? "" })) ?? [], kvLayout: c.layout ?? "list", kvColumns: c.columns ?? 2 }),
+  table: (c) => ({ tablePath: c.tablePath, columns: c.columns ?? [], striped: c.striped ?? true, compact: c.compact ?? false }),
+  statGrid: (c) => ({ statGridItems: c.items ?? [], statGridColumns: c.columns ?? 2, cardStyle: c.cardStyle ?? "filled" }),
+  progressBars: (c) => ({ progressBars: (c.bars as Array<Record<string, unknown>>)?.map((b) => ({ label: b.label ?? "", valuePath: b.valuePath ?? "", maxPath: b.maxPath ?? "", unit: b.unit ?? "", color: b.color ?? "blue" })) ?? [], showPercentage: c.showPercentage ?? true, barSize: c.barSize ?? "md" }),
+  statusIndicator: (c) => ({ statusItems: (c.items as Array<Record<string, unknown>>)?.map((i) => ({ label: i.label ?? "", jsonPath: i.jsonPath ?? "", goodValues: Array.isArray(i.goodValues) ? (i.goodValues as string[]).join(", ") : String(i.goodValues ?? "") })) ?? [], statusLayout: c.layout ?? "list", dotSize: c.dotSize ?? "md" }),
+  countGrid: (c) => ({ countGridItems: c.items ?? [], countGridColumns: c.columns ?? 2, countValueSize: c.valueSize ?? "md" }),
+  raw: (c) => ({ rawJsonPath: c.jsonPath ?? "$", rawMaxHeight: c.maxHeight ?? 300 }),
+  actionButton: (c) => ({ buttonLabel: c.buttonLabel ?? "", buttonColor: c.buttonColor ?? "blue", confirmText: c.confirmText ?? "", successMessage: c.successMessage ?? "" }),
+  customJsx: (c) => ({ template: c.template ?? "" }),
+};
+
+function importJsonToFormValues(imported: CustomWidgetImport): Partial<z.infer<typeof formSchema>> {
+  const displayFields = importToFormValues[imported.displayType]?.(imported.displayConfig as unknown as Record<string, unknown>) ?? {};
+  return {
+    name: imported.name,
+    description: imported.description ?? "",
+    iconUrl: imported.iconUrl ?? "",
+    url: imported.url,
+    authType: imported.authType,
+    headerName: imported.headerName ?? "",
+    method: imported.method,
+    requestBody: imported.requestBody ?? "",
+    displayType: imported.displayType,
+    ...displayFields,
+    secrets: [],
+  };
+}
+
 function extractServerErrors(err: unknown, displayType: string): Record<string, string> {
  const errors: Record<string, string> = {};
  const trpcErr = err as {
@@ -681,6 +713,25 @@ export function CustomWidgetForm({ mode, initialValues, definitionId }: CustomWi
    }
  }, [getPreviewInput, previewMutation]);

+  useEffect(() => {
+    if (mode !== "create") return;
+    const onPaste = (e: ClipboardEvent) => {
+      const raw = e.clipboardData?.getData("text/plain");
+      if (!raw) return;
+      let parsed: unknown;
+      try { parsed = JSON.parse(raw); } catch { return; }
+      const result = customWidgetImportSchema.safeParse(parsed);
+      if (!result.success) return;
+      e.preventDefault();
+      const formValues = importJsonToFormValues(result.data);
+      form.setValues({ ...defaultCreateValues, ...formValues });
+      form.clearErrors();
+      showSuccessNotification({ title: t("action.paste"), message: t("notification.imported" as never, { name: result.data.name }) });
+    };
+    document.addEventListener("paste", onPaste);
+    return () => document.removeEventListener("paste", onPaste);
+  }, [form, t, mode]);
+
  useEffect(() => {
    if (previewRefreshSignal > 0 && hasTestedRef.current) {
      void handlePreviewTest();
@@ -1,11 +1,16 @@
 "use client";

+import { useEffect } from "react";
 import { ActionIcon, Avatar, Badge, Group, Stack, Table, Text } from "@mantine/core";
 import { IconApi, IconPencil } from "@tabler/icons-react";

 import type { RouterOutputs } from "@homarr/api";
+import { clientApi } from "@homarr/api/client";
+import { revalidatePathActionAsync } from "@homarr/common/client";
+import { showErrorNotification, showSuccessNotification } from "@homarr/notifications";
 import { useScopedI18n } from "@homarr/translation/client";
 import { Link } from "@homarr/ui";
+import { customWidgetImportSchema } from "@homarr/validation/custom-widget";

 import { NoResults } from "~/components/no-results";
 import { CustomWidgetRowActions } from "./_custom-widget-actions";
@@ -31,6 +36,32 @@ interface CustomWidgetListProps {

 export const CustomWidgetList = ({ definitions }: CustomWidgetListProps) => {
  const t = useScopedI18n("customWidget");
+  const utils = clientApi.useUtils();
+  const importMutation = clientApi.customWidget.import.useMutation({
+    onSuccess: () => {
+      showSuccessNotification({ title: t("action.paste"), message: "Custom widget imported" });
+      void utils.customWidget.all.invalidate();
+      void revalidatePathActionAsync("/manage/custom-widgets");
+    },
+    onError: (err) => {
+      showErrorNotification({ title: t("action.paste"), message: err.message || "Failed to import" });
+    },
+  });
+
+  useEffect(() => {
+    const onPaste = (e: ClipboardEvent) => {
+      const raw = e.clipboardData?.getData("text/plain");
+      if (!raw) return;
+      let parsed: unknown;
+      try { parsed = JSON.parse(raw); } catch { return; }
+      const result = customWidgetImportSchema.safeParse(parsed);
+      if (!result.success) return;
+      e.preventDefault();
+      importMutation.mutate(result.data);
+    };
+    document.addEventListener("paste", onPaste);
+    return () => document.removeEventListener("paste", onPaste);
+  }, [importMutation]);

  if (definitions.length === 0) {
    return (
@@ -9,6 +9,7 @@ import { Link } from "@homarr/ui";

 import { ManagePageLayout } from "~/components/manage/manage-page-layout";
 import { MobileAffixButton } from "~/components/manage/mobile-affix-button";
+import { InstallWidgetFromStoreButton } from "~/components/store-install/install-from-store-buttons";
 import { CustomWidgetBetaBanner } from "./_beta-banner";
 import { ImportCustomWidgetButton } from "./_custom-widget-actions";
 import { CustomWidgetList } from "./_custom-widget-list";
@@ -28,6 +29,7 @@ export default async function CustomWidgetsPage() {
      title={t("page.list.title")}
      primaryAction={
        <Group gap="xs">
+          <InstallWidgetFromStoreButton />
          <ImportCustomWidgetButton />
          <MobileAffixButton component={Link} href="/manage/custom-widgets/new" leftSection={<IconPlus size={16} />}>
            {t("action.create")}
@@ -0,0 +1,95 @@
+"use client";
+
+import { useState } from "react";
+import { Button } from "@mantine/core";
+import { useDisclosure } from "@mantine/hooks";
+import { IconBuildingStore } from "@tabler/icons-react";
+
+import { clientApi } from "@homarr/api/client";
+import { revalidatePathActionAsync } from "@homarr/common/client";
+import { showErrorNotification, showSuccessNotification } from "@homarr/notifications";
+import { customWidgetImportSchema } from "@homarr/validation/custom-widget";
+
+import { MobileAffixButton } from "~/components/manage/mobile-affix-button";
+import { StoreBrowserModal } from "./store-browser-modal";
+
+function parseWidgetContent(content: string) {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return { ok: false as const, message: "Submission content is not valid JSON" };
+  }
+  const result = customWidgetImportSchema.safeParse(parsed);
+  if (!result.success) {
+    return { ok: false as const, message: result.error.issues[0]?.message ?? "Invalid widget schema" };
+  }
+  return { ok: true as const, data: result.data };
+}
+
+export const InstallWidgetFromStoreButton = () => {
+  const [opened, { open, close }] = useDisclosure(false);
+  const [pendingId, setPendingId] = useState<string | null>(null);
+  const utils = clientApi.useUtils();
+  const importMutation = clientApi.customWidget.import.useMutation({
+    onSuccess: () => {
+      showSuccessNotification({ title: "Marketplace", message: "Custom widget installed" });
+      void utils.customWidget.all.invalidate();
+      void revalidatePathActionAsync("/manage/custom-widgets");
+      setPendingId(null);
+      close();
+    },
+    onError: (err) => {
+      showErrorNotification({ title: "Marketplace", message: err.message || "Failed to install the custom widget" });
+      setPendingId(null);
+    },
+  });
+
+  const handleSelect = (submission: { id: string; content: string }) => {
+    const parsed = parseWidgetContent(submission.content);
+    if (!parsed.ok) {
+      showErrorNotification({ title: "Marketplace", message: parsed.message });
+      return;
+    }
+    setPendingId(submission.id);
+    importMutation.mutate(parsed.data);
+  };
+
+  return (
+    <>
+      <MobileAffixButton variant="default" leftSection={<IconBuildingStore size={16} />} onClick={open}>
+        Install from marketplace
+      </MobileAffixButton>
+      <StoreBrowserModal
+        type="widget"
+        opened={opened}
+        onClose={close}
+        actionLabel="Install"
+        pendingId={pendingId}
+        onSelect={handleSelect}
+      />
+    </>
+  );
+};
+
+export const InstallCssFromStoreButton = ({ onSelect }: { onSelect: (css: string) => void }) => {
+  const [opened, { open, close }] = useDisclosure(false);
+
+  return (
+    <>
+      <Button variant="default" leftSection={<IconBuildingStore size={16} />} onClick={open}>
+        Install from marketplace
+      </Button>
+      <StoreBrowserModal
+        type="css"
+        opened={opened}
+        onClose={close}
+        actionLabel="Use"
+        onSelect={(submission) => {
+          onSelect(submission.content);
+          close();
+        }}
+      />
+    </>
+  );
+};
@@ -0,0 +1,47 @@
+export const STORE_URL = process.env.NEXT_PUBLIC_WIDGET_STORE_URL || "https://store.homarr.dev";
+
+export interface StoreSubmission {
+  id: string;
+  collectionId: string;
+  collectionName: string;
+  type: "css" | "widget";
+  title: string;
+  description: string;
+  schemaVersion: string;
+  content: string;
+  screenshots: string[];
+  upvotes: number;
+  downvotes: number;
+  version: number;
+  author: string;
+  authorName: string;
+  commentCount: number;
+  created: string;
+}
+
+interface PBListResponse {
+  page: number;
+  perPage: number;
+  totalPages: number;
+  totalItems: number;
+  items: StoreSubmission[];
+}
+
+export const getStoreFileUrl = (submission: StoreSubmission, filename: string) =>
+  `${STORE_URL}/api/files/submissions/${submission.id}/${filename}`;
+
+export const fetchStoreSubmissions = async (
+  type: "css" | "widget",
+  page = 1,
+  perPage = 50,
+): Promise<PBListResponse> => {
+  const params = new URLSearchParams({
+    page: String(page),
+    perPage: String(perPage),
+    sort: "-upvotes",
+    filter: `(type='${type}')`,
+  });
+  const response = await fetch(`${STORE_URL}/api/collections/marketplace/records?${params}`);
+  if (!response.ok) throw new Error(`Store request failed (${response.status})`);
+  return response.json() as Promise<PBListResponse>;
+};
@@ -0,0 +1,215 @@
+"use client";
+
+import { useState } from "react";
+import {
+  ActionIcon,
+  Anchor,
+  Alert,
+  Badge,
+  Box,
+  Button,
+  Card,
+  Center,
+  Group,
+  Image,
+  Loader,
+  Modal,
+  Pagination,
+  ScrollArea,
+  SimpleGrid,
+  Stack,
+  Text,
+} from "@mantine/core";
+import { IconChevronLeft, IconChevronRight, IconExternalLink } from "@tabler/icons-react";
+import { useQuery } from "@tanstack/react-query";
+
+import type { StoreSubmission } from "./store-api";
+import { fetchStoreSubmissions, getStoreFileUrl } from "./store-api";
+
+const MARKETPLACE_URL = process.env.NEXT_PUBLIC_MARKETPLACE_URL || "https://homarr.dev/marketplace";
+
+interface Props {
+  type: "css" | "widget";
+  opened: boolean;
+  onClose: () => void;
+  onSelect: (submission: StoreSubmission) => void;
+  actionLabel: string;
+  pendingId?: string | null;
+}
+
+const displayName = (submission: StoreSubmission) => submission.authorName;
+
+export const StoreBrowserModal = ({ type, opened, onClose, onSelect, actionLabel, pendingId }: Props) => {
+  const [page, setPage] = useState(1);
+  const handleClose = () => {
+    setPage(1);
+    onClose();
+  };
+  const { data, isLoading, error } = useQuery({
+    queryKey: ["store-submissions", type, page],
+    queryFn: () => fetchStoreSubmissions(type, page),
+    enabled: opened,
+  });
+
+  const errorText = error instanceof Error ? error.message : "unknown error";
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={handleClose}
+      title={
+        <Group gap="sm">
+          <Text fw={600}>Install from marketplace</Text>
+          <Anchor
+            href={MARKETPLACE_URL}
+            target="_blank"
+            rel="noopener noreferrer"
+            size="xs"
+            style={{ display: "inline-flex", alignItems: "center", gap: 4 }}
+          >
+            Open Marketplace <IconExternalLink size={12} />
+          </Anchor>
+        </Group>
+      }
+      size={1200}
+      scrollAreaComponent={ScrollArea.Autosize}
+    >
+      <Stack gap="md">
+        {isLoading && (
+          <Center py="xl">
+            <Loader />
+          </Center>
+        )}
+
+        {error && <Alert color="red">Failed to load the marketplace: {errorText}</Alert>}
+
+        {data && data.items.length === 0 && (
+          <Text c="dimmed" ta="center" py="xl">
+            No submissions available yet.
+          </Text>
+        )}
+
+        {data && data.items.length > 0 && (
+          <>
+            <SimpleGrid cols={{ base: 1, sm: 2, lg: 3 }} spacing="md">
+              {data.items.map((submission) => (
+                <SubmissionCard
+                  key={submission.id}
+                  submission={submission}
+                  actionLabel={actionLabel}
+                  pending={pendingId === submission.id}
+                  onSelect={() => onSelect(submission)}
+                />
+              ))}
+            </SimpleGrid>
+
+            {data.totalPages > 1 && (
+              <Center>
+                <Pagination total={data.totalPages} value={page} onChange={setPage} />
+              </Center>
+            )}
+          </>
+        )}
+      </Stack>
+    </Modal>
+  );
+};
+
+const SubmissionCard = ({
+  submission,
+  actionLabel,
+  pending,
+  onSelect,
+}: {
+  submission: StoreSubmission;
+  actionLabel: string;
+  pending: boolean;
+  onSelect: () => void;
+}) => {
+  const screenshots = submission.screenshots ?? [];
+  const [imgIdx, setImgIdx] = useState(0);
+  const score = submission.upvotes - submission.downvotes;
+  const scorePrefix = score > 0 ? "+" : "";
+
+  return (
+    <Card withBorder padding={0}>
+      {screenshots.length > 0 && (
+        <Box pos="relative">
+          <Image
+            src={screenshots[imgIdx] ? getStoreFileUrl(submission, screenshots[imgIdx]) : undefined}
+            alt={submission.title}
+            h={180}
+            fit="cover"
+          />
+          {screenshots.length > 1 && (
+            <>
+              <ActionIcon
+                variant="filled"
+                color="dark"
+                size="xs"
+                pos="absolute"
+                top="50%"
+                left={4}
+                style={{ transform: "translateY(-50%)" }}
+                onClick={() => setImgIdx((i) => (i - 1 + screenshots.length) % screenshots.length)}
+              >
+                <IconChevronLeft size={12} />
+              </ActionIcon>
+              <ActionIcon
+                variant="filled"
+                color="dark"
+                size="xs"
+                pos="absolute"
+                top="50%"
+                right={4}
+                style={{ transform: "translateY(-50%)" }}
+                onClick={() => setImgIdx((i) => (i + 1) % screenshots.length)}
+              >
+                <IconChevronRight size={12} />
+              </ActionIcon>
+            </>
+          )}
+        </Box>
+      )}
+
+      <Stack gap={4} p="sm">
+        <Group gap="xs" wrap="nowrap">
+          <Text fw={600} size="sm" truncate style={{ flex: 1 }}>
+            {submission.title}
+          </Text>
+          <Badge variant="light" size="sm" style={{ flexShrink: 0 }}>
+            {scorePrefix}
+            {score}
+          </Badge>
+        </Group>
+
+        <Text size="xs" c="dimmed">
+          {displayName(submission)} · v{submission.version}
+        </Text>
+
+        {submission.description && (
+          <Text size="xs" c="dimmed" lineClamp={2}>
+            {submission.description}
+          </Text>
+        )}
+
+        <Group gap="xs" mt={4}>
+          <Button size="xs" style={{ flex: 1 }} loading={pending} onClick={onSelect}>
+            {actionLabel}
+          </Button>
+          <ActionIcon
+            variant="light"
+            size="sm"
+            component="a"
+            href={`${MARKETPLACE_URL}/${submission.id}/`}
+            target="_blank"
+            rel="noopener noreferrer"
+            aria-label="View in marketplace"
+          >
+            <IconExternalLink size={14} />
+          </ActionIcon>
+        </Group>
+      </Stack>
+    </Card>
+  );
+};