fix: ensure react query client is stable between renders (#1009)

The `QueryClient` constructed in `Sdk.tsx` was subject to being
recreated during development mode hot reloads and it was causing
unnecessary query cache invalidations. This change refactors the code so
that the `QueryClient` is only created once per client-side session.
This includes the error handling logic which it depends on. Error
handling functions did not need to be threaded through React context so
that was all removed in favor of simpler exported functions from
`@/lib/errors`.

Author: disintegrator

.changeset/yellow-days-guess.md

@@ -0,0 +1,6 @@
+---
+"dashboard": patch
+---
+
+Ensure stable QueryClient is used for lifetime of web app especially during
+development mode hot reloads.

client/dashboard/src/components/content-error-boundary.tsx

@@ -1,18 +1,16 @@
 import { Button } from "@speakeasy-api/moonshine";
 import { Card } from "@/components/ui/card";
 import { Spinner } from "@/components/ui/spinner";
-import { useErrorHandler } from "@/contexts/ErrorHandler";
 import { Icon, Stack } from "@speakeasy-api/moonshine";
 import { ReactNode, Suspense } from "react";
 import { ErrorBoundary as ReactErrorBoundary } from "react-error-boundary";
+import { handleError } from "@/lib/errors";
 
 interface ContentErrorFallbackProps {
   error: Error;
 }
 
 function ContentErrorFallback({ error }: ContentErrorFallbackProps) {
-  const { handleError } = useErrorHandler();
-
   // Log error to our error handler for consistent logging
   handleError(error, { silent: true });
 

client/dashboard/src/contexts/ErrorHandler.tsx

@@ -1,4 +1,3 @@
-import { useErrorHandler } from "@/contexts/ErrorHandler";
 import { getServerURL } from "@/lib/utils";
 import { datadogRum } from "@datadog/browser-rum";
 import { Gram } from "@gram/client";
@@ -8,6 +7,7 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { createContext, useContext, useEffect, useMemo, useRef } from "react";
 import { useLocation, useParams } from "react-router";
 import { useTelemetry } from "./Telemetry";
+import { handleError } from "@/lib/errors";
 
 export const SdkContext = createContext<Gram>({} as Gram);
 
@@ -16,39 +16,34 @@ export const useSdkClient = () => {
   return client;
 };
 
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      throwOnError: true,
+      retry: (failureCount, error: Error) => {
+        // Don't retry on 4xx errors
+        if (error && typeof error === "object" && "status" in error) {
+          const status = (error as unknown as { status: number }).status;
+          if (status >= 400 && status < 500) {
+            return false;
+          }
+        }
+        // Default retry logic for other errors
+        return failureCount < 3;
+      },
+    },
+    mutations: {
+      onError: (error: Error) => {
+        handleError(error, { title: "Request failed" });
+      },
+    },
+  },
+});
+
 export const SdkProvider = ({ children }: { children: React.ReactNode }) => {
   const { projectSlug } = useSlugs();
-  const { handleError } = useErrorHandler();
   const telemetry = useTelemetry();
 
-  const queryClient = useMemo(
-    () =>
-      new QueryClient({
-        defaultOptions: {
-          queries: {
-            throwOnError: true,
-            retry: (failureCount, error: Error) => {
-              // Don't retry on 4xx errors
-              if (error && typeof error === "object" && "status" in error) {
-                const status = (error as unknown as { status: number }).status;
-                if (status >= 400 && status < 500) {
-                  return false;
-                }
-              }
-              // Default retry logic for other errors
-              return failureCount < 3;
-            },
-          },
-          mutations: {
-            onError: (error: Error) => {
-              handleError(error, { title: "Request failed" });
-            },
-          },
-        },
-      }),
-    [handleError],
-  );
-
   const previousProjectSlug = useRef(projectSlug);
 
   // Memoize the httpClient and gram instances

client/dashboard/src/contexts/Sdk.tsx

@@ -0,0 +1,72 @@
+import { Type } from "@/components/ui/type";
+import { Stack } from "@speakeasy-api/moonshine";
+import { toast } from "sonner";
+
+interface ErrorHandlerOptions {
+  title?: string;
+  persist?: boolean;
+  customAction?: {
+    label: string;
+    onClick: () => void;
+  };
+  silent?: boolean;
+}
+
+export function handleError(
+  error: Error | string,
+  options: ErrorHandlerOptions = {},
+) {
+  const {
+    title = "Error",
+    persist = false,
+    customAction,
+    silent = false,
+  } = options;
+
+  const errorMessage = typeof error === "string" ? error : error.message;
+
+  // Log error for debugging
+  console.error("Error handled:", error);
+
+  // Show toast notification unless silent
+  if (!silent) {
+    toast.error(
+      <Stack gap={1}>
+        <Type variant="subheading" className="text-destructive!">
+          {title}
+        </Type>
+        <Type small muted>
+          {errorMessage}
+        </Type>
+      </Stack>,
+      {
+        duration: persist ? Infinity : 5000,
+        action: customAction
+          ? {
+              label: customAction.label,
+              onClick: customAction.onClick,
+            }
+          : undefined,
+      },
+    );
+  }
+}
+
+export function handleAPIError(error: unknown, defaultMessage?: string) {
+  let errorMessage = defaultMessage || "An unexpected error occurred";
+
+  if (error instanceof Error) {
+    errorMessage = error.message;
+  } else if (typeof error === "string") {
+    errorMessage = error;
+  } else if (error && typeof error === "object") {
+    // Handle API response errors
+    if ("message" in error && typeof error.message === "string") {
+      errorMessage = error.message;
+    } else if ("error" in error && typeof error.error === "string") {
+      errorMessage = error.error;
+    }
+  }
+
+  handleError(errorMessage);
+}

client/dashboard/src/hooks/useApiError.ts

@@ -1,7 +1,6 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { Toaster } from "@/components/ui/sonner";
-import { ErrorHandlerProvider } from "@/contexts/ErrorHandler";
 import App from "./App.tsx";
 
 createRoot(document.getElementById("root")!).render(
@@ -10,9 +9,7 @@ createRoot(document.getElementById("root")!).render(
       @import
       url('https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&family=Mona+Sans:ital,wght@0,200..900;1,200..900&family=Roboto:ital,wght@0,100;0,300;0,400;0,500;0,700;0,900;1,100;1,300;1,400;1,500;1,700;1,900&family=Space+Mono:ital,wght@0,400;0,700;1,400;1,700&display=swap');
     </style>
-    <ErrorHandlerProvider>
-      <App />
-      <Toaster />
-    </ErrorHandlerProvider>
+    <App />
+    <Toaster />
   </StrictMode>,
 );

client/dashboard/src/lib/errors.tsx

@@ -5,7 +5,6 @@ import { Card, Cards } from "@/components/ui/card";
 import { UpdatedAt } from "@/components/updated-at";
 import { useSession } from "@/contexts/Auth";
 import { useTelemetry } from "@/contexts/Telemetry";
-import { useApiError } from "@/hooks/useApiError";
 import { useRoutes } from "@/routes";
 import { Environment } from "@gram/client/models/components/environment.js";
 import {
@@ -16,6 +15,7 @@ import { Plus } from "lucide-react";
 import { useState } from "react";
 import { Outlet } from "react-router";
 import { Button } from "@speakeasy-api/moonshine";
+import { handleAPIError } from "@/lib/errors";
 export function EnvironmentsRoot() {
   return <Outlet />;
 }
@@ -35,7 +35,6 @@ export default function Environments() {
   const session = useSession();
   const routes = useRoutes();
   const telemetry = useTelemetry();
-  const { handleApiError } = useApiError();
 
   const [createEnvironmentDialogOpen, setCreateEnvironmentDialogOpen] =
     useState(false);
@@ -50,7 +49,7 @@ export default function Environments() {
       routes.environments.environment.goTo(data.slug);
     },
     onError: (error) => {
-      handleApiError(error, "Failed to create environment");
+      handleAPIError(error, "Failed to create environment");
       telemetry.capture("environment_event", {
         action: "environment_creation_failed",
         error: error.message,