TanStack Query

Statusseite abrufen mit TanStack Query — useQuery-Guide

PulseAPI-Status-Endpoint mit useQuery abrufen. Cache, Refetch on Focus, Polling-Interval und SSE-Realtime — alles in einem typisierten Hook.

Kostenlos starten Eigene via API bauen

Drei Wege für eine Statusseite für TanStack Query

Wähle die Kontrolltiefe — kein Code, Low-Code oder Full Headless.

Gehostet

TanStack Query-Endpoint hinzufügen, CNAME auf status.deinedomain.com zeigen, fertig. In 5 Minuten.

Headless

Public API nutzen, eigene UI direkt in der TanStack Query-App bauen. Volle Kontrolle über Design und Branding.

API ansehen

Eingebettete Badges

SVG-Uptime- und -Status-Badges in README oder Landing Page einbauen. Aktualisiert sich alle 5 Minuten.

Diesen Health-Endpoint in deine TanStack Query-App einfügen

Kopieren, einfügen, PulseAPI auf die URL richten. 200 gesund, 503 degradiert.

app/status/use-status-query.ts

import { useQuery } from '@tanstack/react-query'

interface StatusData {
  page: { title: string; customDomain: string | null }
  overallStatus: 'operational' | 'degraded' | 'down' | 'maintenance' | 'unknown'
  endpoints: Array<{
    id: string
    name: string
    status: string
    uptime24h: number
    avgResponseTime: number
  }>
}

export const useStatusQuery = (slug: string) =>
  useQuery<StatusData>({
    queryKey: ['status', slug],
    queryFn: async () => {
      const r = await fetch(`https://api.pulseapi.tech/status/${slug}`)
      if (!r.ok) throw new Error(`Status ${r.status}`)
      return r.json()
    },
    staleTime: 30_000,
    refetchInterval: 30_000,
    refetchOnWindowFocus: true,
  })

Nutze staleTime und refetchInterval von 30 Sekunden, passend zu unserem SSE-Heartbeat. Für Realtime-Updates ohne Polling kombiniere diesen Hook mit unserem /sse/status/:slug-Stream und patche den Cache per queryClient.setQueryData bei Events.

Was in TanStack Query-Apps kaputt geht — und wie man es fängt

Veralteter Status in lange offenen Tabs

Ein nachts offenes Dashboard zeigt grünen Banner, obwohl Production längst down ist. refetchInterval + refetchOnWindowFocus hält den Cache ehrlich.

Flash falschen Inhalts während Revalidierung

placeholderData + keepPreviousData zeigt den letzten guten Status weiter, während ein Refetch läuft — kein Flackern zwischen "operational" und Skeleton.

Zu viele parallele Requests aus verschachtelten Komponenten

Mehrere Komponenten, die useStatusQuery aufrufen, würden je einen Request feuern — React Query dedupliziert per queryKey, sodass pro Slug nur ein laufender Fetch existiert.

Headless-Ansatz

Statusseite gefällt dir nicht? Bau sie in TanStack Query selbst.

Unsere API liefert dieselben Daten wie unsere gehostete UI. Volle OpenAPI-Spec unter api.pulseapi.tech/docs.

components/StatusBanner.tsx — zeigt in der App einen Inline-Banner, sobald PulseAPI einen degradierten oder ausgefallenen Status meldet.

import { useStatusQuery } from './use-status-query'

export function StatusBanner({ slug }: { slug: string }) {
  const { data, isLoading, error } = useStatusQuery(slug)

  if (isLoading) return <div className="skeleton" />
  if (error) return null
  if (!data) return null
  if (data.overallStatus === 'operational') return null

  return (
    <a href={`https://${data.page.customDomain}`} className="banner">
      {data.overallStatus === 'down' ? 'Service disruption' : 'Degraded service'}
      {' — '}
      {data.endpoints.filter((e) => e.status !== 'operational').length} affected
    </a>
  )
}

API erkunden

TanStack Query-Monitoring — FAQ

Wie kombiniere ich useQuery mit SSE für Realtime-Updates?

Öffne eine EventSource auf /sse/status/:slug in einem useEffect und rufe bei jedem Event queryClient.setQueryData(["status", slug], to merge event patches into the existing cache entry auf. So bleiben useQuery-Abonnenten ohne Polling aktuell.

Funktioniert das mit TanStack Query v4 und v5?

Beide. In v4 heißt es cacheTime, in v5 wurde es zu gcTime umbenannt. isLoading in v5 ist strikt "erster Load"; für generelle In-Flight-Indikatoren isPending + isFetching nutzen.

Kann ich den Status server-seitig mit Next.js oder Remix prefetchen?

Ja. queryClient.prefetchQuery im Server Component oder Loader aufrufen, den Tree in HydrationBoundary (v5) oder Hydrate (v4) mit dehydriertem State einwickeln. Der useStatusQuery-Hook liest beim ersten Render aus dem hydrierten Cache — kein Client-Flackern.

Ist es sicher, meinen Org-API-Key in useQuery zu nutzen?

Nein — jeder Key im Browser-JS ist public. Der öffentliche Status-Endpoint braucht keine Auth; Org-API-Keys nur server-seitig. Proxy über eine Backend-Route (/api/status) und rufe diesen Proxy aus useQuery, wenn Auth nötig ist.

Deine TanStack Query-App in 5 Minuten überwachen

Kostenloser Tarif. Keine Kreditkarte. Endpoint hinzufügen, Alerts erhalten.

Kostenlos starten Andere Frameworks ansehen