Real-Time Dashboard in Next.js with TanStack Query + Zustand

// app/(dashboard)/dashboard/page.tsx — Server Component
import { auth } from "@/lib/auth";
import { redirect } from "next/navigation";
import { DashboardClient } from "./dashboard-client";
import { getInitialStats } from "@/lib/stats";

export default async function DashboardPage() {
  const session = await auth();
  if (!session) redirect("/login");

  // Initial data fetch on the server — no loading spinner on first load
  const initialStats = await getInitialStats(session.user.id);

  return <DashboardClient initialStats={initialStats} userId={session.user.id} />;
}

// app/(dashboard)/dashboard/dashboard-client.tsx
"use client";

import { useQuery, QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { useDashboardStore } from "@/store/dashboard";

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 30_000,    // Consider data stale after 30 seconds
      gcTime: 5 * 60_000,   // Keep unused data in cache for 5 minutes
      retry: 2,
      retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 10_000),
    },
  },
});

export function DashboardClient({
  initialStats,
  userId,
}: {
  initialStats: UsageStats;
  userId: string;
}) {
  return (
    <QueryClientProvider client={queryClient}>
      <DashboardContent initialStats={initialStats} userId={userId} />
    </QueryClientProvider>
  );
}

function DashboardContent({
  initialStats,
  userId,
}: {
  initialStats: UsageStats;
  userId: string;
}) {
  // Read filter state from Zustand
  const { timeRange, environment } = useDashboardStore();

  const { data: stats, isLoading, error, dataUpdatedAt } = useQuery({
    queryKey: ["usage-stats", userId, timeRange, environment],
    queryFn: () => fetchUsageStats({ userId, timeRange, environment }),
    initialData: initialStats,
    refetchInterval: 30_000, // Poll every 30 seconds
    refetchIntervalInBackground: false, // Stop polling when tab is not focused
  });

  if (isLoading && !stats) return <DashboardSkeleton />;
  if (error) return <DashboardError error={error} />;

  return (
    <div>
      <StatsGrid stats={stats} />
      <ActivityChart userId={userId} timeRange={timeRange} />
      <LastUpdated timestamp={dataUpdatedAt} />
    </div>
  );
}

// store/dashboard.ts
import { create } from "zustand";
import { persist } from "zustand/middleware";

type TimeRange = "1h" | "24h" | "7d" | "30d";
type Environment = "live" | "test" | "all";

interface DashboardState {
  timeRange: TimeRange;
  environment: Environment;
  selectedUserId: string | null;

  setTimeRange: (range: TimeRange) => void;
  setEnvironment: (env: Environment) => void;
  setSelectedUser: (userId: string | null) => void;
  reset: () => void;
}

const initialState = {
  timeRange: "24h" as TimeRange,
  environment: "live" as Environment,
  selectedUserId: null,
};

export const useDashboardStore = create<DashboardState>()(
  persist(
    (set) => ({
      ...initialState,
      setTimeRange: (timeRange) => set({ timeRange }),
      setEnvironment: (environment) => set({ environment }),
      setSelectedUser: (selectedUserId) => set({ selectedUserId }),
      reset: () => set(initialState),
    }),
    {
      name: "dashboard-filters",
      partialize: (state) =>
        // Only persist the filter values, not the setter functions
        ({
          timeRange: state.timeRange,
          environment: state.environment,
          // Don't persist selectedUserId — clear on reload
        }),
    }
  )
);

// components/dashboard/TimeRangeSelector.tsx
"use client";

import { useDashboardStore } from "@/store/dashboard";

const TIME_RANGES = [
  { value: "1h" as const, label: "1 hour" },
  { value: "24h" as const, label: "24 hours" },
  { value: "7d" as const, label: "7 days" },
  { value: "30d" as const, label: "30 days" },
];

export function TimeRangeSelector() {
  const { timeRange, setTimeRange } = useDashboardStore();

  return (
    <div className="flex gap-1 rounded-lg border p-1">
      {TIME_RANGES.map(({ value, label }) => (
        <button
          key={value}
          onClick={() => setTimeRange(value)}
          className={`rounded px-3 py-1 text-sm transition-colors ${
            timeRange === value
              ? "bg-primary text-primary-foreground"
              : "hover:bg-muted"
          }`}
        >
          {label}
        </button>
      ))}
    </div>
  );
}

// components/dashboard/ActivityChart.tsx
"use client";

import { useQuery } from "@tanstack/react-query";
import { useDashboardStore } from "@/store/dashboard";

interface DayActivity {
  date: string;  // "2026-04-01"
  count: number;
}

export function ActivityChart({ userId }: { userId: string }) {
  const { timeRange, environment } = useDashboardStore();

  const { data: activityData } = useQuery<DayActivity[]>({
    queryKey: ["activity-chart", userId, timeRange, environment],
    queryFn: () => fetchActivityData({ userId, timeRange, environment }),
    refetchInterval: 60_000, // Chart updates less frequently than KPIs
  });

  if (!activityData || activityData.length === 0) {
    return <div className="h-32 animate-pulse rounded bg-muted" />;
  }

  const maxCount = Math.max(...activityData.map((d) => d.count), 1);

  return (
    <div>
      <h3 className="mb-3 text-sm font-medium text-muted-foreground">
        API Calls
      </h3>
      <div className="flex h-32 items-end gap-0.5">
        {activityData.map((day, i) => {
          const pct = (day.count / maxCount) * 100;
          const minHeight = day.count > 0 ? 3 : 0; // Ensure non-zero days are visible

          return (
            <div
              key={i}
              className="group relative flex flex-1 flex-col items-center justify-end"
            >
              <div
                className="w-full rounded-t bg-primary/60 transition-all group-hover:bg-primary"
                style={{ height: `${Math.max(pct, minHeight)}%` }}
              />
              {/* Tooltip on hover */}
              <div className="pointer-events-none absolute bottom-full mb-1 hidden whitespace-nowrap rounded bg-popover px-2 py-1 text-xs shadow group-hover:block">
                {formatDate(day.date)}: {day.count.toLocaleString()} calls
              </div>
            </div>
          );
        })}
      </div>
      {/* X-axis: first and last date labels */}
      <div className="mt-1 flex justify-between text-xs text-muted-foreground">
        <span>{formatDateShort(activityData[0]?.date)}</span>
        <span>{formatDateShort(activityData[activityData.length - 1]?.date)}</span>
      </div>
    </div>
  );
}

function formatDate(dateStr: string): string {
  return new Date(dateStr).toLocaleDateString("en-GB", {
    day: "2-digit",
    month: "short",
  });
}

function formatDateShort(dateStr: string | undefined): string {
  if (!dateStr) return "";
  return new Date(dateStr).toLocaleDateString("en-GB", {
    day: "2-digit",
    month: "short",
  });
}

// instrumentation.ts (Next.js instrumentation hook)
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const Sentry = await import("@sentry/nextjs");
    Sentry.init({
      dsn: process.env.SENTRY_DSN,
      environment: process.env.NODE_ENV,
      tracesSampleRate: 0.1, // Sample 10% of transactions for performance monitoring
      // Don't send errors from localhost
      enabled: process.env.NODE_ENV === "production",
    });
  }
}

// components/dashboard/ErrorBoundary.tsx
"use client";

import * as Sentry from "@sentry/nextjs";
import { ErrorBoundary } from "@sentry/nextjs";
import type { ReactNode } from "react";

interface DashboardErrorBoundaryProps {
  panelName: string;
  children: ReactNode;
}

export function DashboardErrorBoundary({
  panelName,
  children,
}: DashboardErrorBoundaryProps) {
  return (
    <ErrorBoundary
      fallback={({ error, resetError }) => (
        <div className="rounded-lg border border-destructive/30 bg-destructive/10 p-4">
          <p className="text-sm text-destructive">
            Failed to load {panelName}.{" "}
            <button
              onClick={resetError}
              className="underline hover:no-underline"
            >
              Retry
            </button>
          </p>
          {process.env.NODE_ENV === "development" && (
            <pre className="mt-2 text-xs text-muted-foreground">
              {error instanceof Error ? error.message : String(error)}
            </pre>
          )}
        </div>
      )}
      onError={(error, componentStack) => {
        // Tag the error with the panel name for filtering in Sentry
        Sentry.withScope((scope) => {
          scope.setTag("dashboard_panel", panelName);
          scope.setExtra("componentStack", componentStack);
          Sentry.captureException(error);
        });
      }}
    >
      {children}
    </ErrorBoundary>
  );
}

  <UsageStatsPanel userId={userId} />

  <ActivityChart userId={userId} />

  <RecentChecksTable userId={userId} />

// lib/query-client.ts
import { QueryClient } from "@tanstack/react-query";
import * as Sentry from "@sentry/nextjs";

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 30_000,
      retry: 2,
    },
    mutations: {
      onError: (error) => {
        Sentry.captureException(error, {
          tags: { source: "tanstack-mutation" },
        });
      },
    },
  },
  // TanStack Query v5: global error handling
  mutationCache: undefined, // configured via QueryCache below
});

// Capture query errors globally
queryClient.getQueryCache().config = {
  onError: (error, query) => {
    // Only capture after all retries are exhausted
    if (query.state.fetchFailureCount === 2) {
      Sentry.captureException(error, {
        tags: {
          source: "tanstack-query",
          queryKey: JSON.stringify(query.queryKey),
        },
      });
    }
  },
};

// After revoking an API key
await revokeApiKey(keyId);
queryClient.invalidateQueries({ queryKey: ["user-api-keys", userId] });
queryClient.invalidateQueries({ queryKey: ["usage-stats", userId] });

useQuery({
  queryKey: ["activity", userId],
  queryFn: fetchActivity,
  select: (data) => ({
    chartData: data.map((d) => ({ date: d.day, count: d.total })),
    totalCalls: data.reduce((sum, d) => sum + d.total, 0),
  }),
});