fix: handle lazy startup failures

apps/nextjs/src/components/board/items/item-content.tsx

@@ -5,6 +5,7 @@ import { useElementSize } from "@mantine/hooks";
 import { QueryErrorResetBoundary, useQueryClient } from "@tanstack/react-query";
 import combineClasses from "clsx";
 import { NoIntegrationSelectedError } from "@homarr/widgets/errors/classes";
+import type { FallbackProps } from "react-error-boundary";
 import { ErrorBoundary } from "react-error-boundary";
 
 import { useRequiredBoard } from "@homarr/boards/context";
@@ -33,6 +34,12 @@ const getOverflowFromKind = (kind: SectionItem["kind"]) => {
   return undefined;
 };
 
+const WidgetDefinitionLoadError = ({ error, resetErrorBoundary }: FallbackProps) => (
+  <Center className={classes.itemCard} h="100%">
+    <WidgetError error={error} resetErrorBoundary={resetErrorBoundary} />
+  </Center>
+);
+
 export const BoardItemContent = ({ item }: BoardItemContentProps) => {
   const { ref, width, height } = useElementSize<HTMLDivElement>();
   const board = useRequiredBoard();
@@ -40,21 +47,23 @@ export const BoardItemContent = ({ item }: BoardItemContentProps) => {
 
   return (
     <>
-      <Suspense
-        fallback={
-          <Center ref={ref} className={classes.itemCard} h="100%">
-            <Loader size="sm" />
-          </Center>
-        }
-      >
-        <LoadedBoardItemContent
-          item={item}
-          width={width}
-          height={height}
-          widgetStateRef={widgetStateRef}
-          innerRef={ref}
-        />
-      </Suspense>
+      <ErrorBoundary resetKeys={[item.kind]} fallbackRender={WidgetDefinitionLoadError}>
+        <Suspense
+          fallback={
+            <Center ref={ref} className={classes.itemCard} h="100%">
+              <Loader size="sm" />
+            </Center>
+          }
+        >
+          <LoadedBoardItemContent
+            item={item}
+            width={width}
+            height={height}
+            widgetStateRef={widgetStateRef}
+            innerRef={ref}
+          />
+        </Suspense>
+      </ErrorBoundary>
       {item.advancedOptions.title?.trim() && (
         <Badge
           pos="absolute"

apps/nextjs/src/components/integration/integration-multi-select-grid.tsx

@@ -43,7 +43,11 @@ export const IntegrationMultiSelectGrid = ({
     [selectedKindsArray, onSelectionChange],
   );
 
-  const { data: integrations = [], isPending } = useQuery({
+  const {
+    data: integrations = [],
+    isPending,
+    isError,
+  } = useQuery({
     queryKey: ["widget-integrations", { enableMockIntegration, onboarding }],
     queryFn: () => buildSortedIntegrations({ enableMockIntegration, onboarding }),
   });
@@ -136,7 +140,14 @@ export const IntegrationMultiSelectGrid = ({
         );
       })}
 
-      {!isPending && filtered.length === 0 && (
+      {isError && (
+        <Center p="xl">
+          <Text c="red" role="alert">
+            {t("common.error")}
+          </Text>
+        </Center>
+      )}
+      {!isPending && !isError && filtered.length === 0 && (
         <Center p="xl">
           <Text c="dimmed">{t("common.noResults")}</Text>
         </Center>

apps/nextjs/src/components/integration/integration-select-grid.tsx

@@ -20,7 +20,11 @@ export const IntegrationSelectGrid = ({ onSelect, enableMockIntegration = false
   const [search, setSearch] = useState("");
   const t = useI18n();
 
-  const { data: integrations = [], isPending } = useQuery({
+  const {
+    data: integrations = [],
+    isPending,
+    isError,
+  } = useQuery({
     queryKey: ["widget-integrations", { enableMockIntegration }],
     queryFn: () => buildSortedIntegrations({ enableMockIntegration }),
   });
@@ -89,7 +93,14 @@ export const IntegrationSelectGrid = ({ onSelect, enableMockIntegration = false
         </Card>
       ))}
 
-      {!isPending && filtered.length === 0 && (
+      {isError && (
+        <Center p="xl">
+          <Text c="red" role="alert">
+            {t("common.error")}
+          </Text>
+        </Center>
+      )}
+      {!isPending && !isError && filtered.length === 0 && (
         <Center p="xl">
           <Text c="dimmed">{t("common.noResults")}</Text>
         </Center>

apps/nextjs/src/instrumentation.spec.ts

@@ -52,4 +52,22 @@ describe("Next instrumentation", () => {
     expect(tasksStarted).not.toHaveBeenCalled();
     expect(websocketStarted).not.toHaveBeenCalled();
   });
+
+  test("isolates embedded service startup failures", async () => {
+    const websocketStarted = vi.fn();
+    vi.stubEnv("NODE_ENV", "production");
+    vi.stubEnv("NEXT_RUNTIME", "nodejs");
+    vi.doMock("@homarr/tasks", () => {
+      throw new Error("task startup failed");
+    });
+    vi.doMock("@homarr/websocket", () => {
+      websocketStarted();
+      return {};
+    });
+
+    const { register } = await import("./instrumentation");
+
+    await expect(register()).resolves.toBeUndefined();
+    expect(websocketStarted).toHaveBeenCalledOnce();
+  });
 });

apps/nextjs/src/instrumentation.ts

@@ -1,7 +1,22 @@
+import { createLogger } from "@homarr/core/infrastructure/logs";
+
+const logger = createLogger({ module: "instrumentation" });
+
 export async function register() {
   if (process.env.NEXT_RUNTIME !== "nodejs") return;
   if (process.env.NODE_ENV !== "production") return;
 
-  await import("@homarr/tasks");
-  await import("@homarr/websocket");
+  const services = [
+    { name: "tasks", start: () => import("@homarr/tasks") },
+    { name: "websocket", start: () => import("@homarr/websocket") },
+  ];
+  const results = await Promise.allSettled(services.map(({ start }) => start()));
+
+  for (const [index, result] of results.entries()) {
+    if (result.status === "rejected") {
+      logger.error(
+        new Error(`Failed to start embedded ${services[index]?.name ?? "unknown"} service`, { cause: result.reason }),
+      );
+    }
+  }
 }