Skip to main content

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

useVersionInfo

Hooks for fetching and managing application version information from the /api/version endpoint. Includes the primary data-fetching hook and a utility hook for cache management.

Source file: template/hooks/use-version-info.ts

Overview​

useVersionInfo provides real-time version information about the deployed application, including the latest commit hash, date, author, and repository details. It uses TanStack Query for caching with configurable refresh intervals and intelligent retry logic. The companion useVersionInfoUtils hook offers cache management utilities for prefetching, invalidating, and directly reading/writing version data in the query cache.

Exported Members​

ExportKindPurpose
useVersionInfoFunction (hook)Primary hook for fetching version info with auto-refresh
useVersionInfoUtilsFunction (hook)Cache management utilities (prefetch, invalidate, get/set cache)
VERSION_INFO_QUERY_KEYConstantTanStack Query key: ['version-info']

useVersionInfo​

function useVersionInfo(options?: UseVersionInfoOptions): UseVersionInfoReturn

Options​

interface UseVersionInfoOptions {
  refreshInterval?: number;   // Auto-refresh interval in ms (default: 300000 / 5 min)
  retryOnError?: boolean;     // Enable retry on failure (default: true)
  enabled?: boolean;          // Enable/disable the query (default: true)
}
OptionTypeDefaultDescription
refreshIntervalnumber300000 (5 min)Interval for automatic refetching. Set to 0 to disable.
retryOnErrorbooleantrueWhether to retry on network/server errors
enabledbooleantrueWhether the query should execute

Return Value​

interface UseVersionInfoReturn {
  versionInfo: VersionInfo | null;
  isLoading: boolean;
  isError: boolean;
  error: UseVersionInfoError | null;
  refetch: () => Promise<any>;
  isStale: boolean;
  dataUpdatedAt: number;
  invalidateVersionInfo: () => Promise<void>;
}
PropertyTypeDescription
versionInfoVersionInfo | nullThe version data, or null if not yet loaded
isLoadingbooleantrue while the initial fetch is in progress
isErrorbooleantrue if the query has errored
errorUseVersionInfoError | nullError details including message and optional HTTP status
refetch() => Promise<any>Manually trigger a refetch
isStalebooleanWhether the cached data is considered stale
dataUpdatedAtnumberTimestamp of when data was last successfully fetched
invalidateVersionInfo() => Promise<void>Invalidate the cache, triggering a refetch

VersionInfo Type​

interface VersionInfo {
  commit: string;
  date: string;
  message: string;
  author: string;
  repository: string;
  lastSync: string;
  branch?: string;
}

Error Type​

interface UseVersionInfoError {
  message: string;
  status?: number;
}

Cache Configuration​

SettingValue
Query key['version-info']
staleTime5 minutes
gcTime30 minutes
refetchOnWindowFocusfalse
refetchOnReconnecttrue
refetchOnMountfalse
RetryUp to 2 attempts for server/network errors; no retry for 4xx client errors
Retry delayExponential backoff, capped at 30 seconds

Data Validation​

The hook validates the API response, requiring that commit, date, and author fields are present. If validation fails, a 422 status error is thrown.

useVersionInfoUtils​

Utility hook for managing the version info query cache across the application.

function useVersionInfoUtils(): {
  prefetchVersionInfo: () => Promise<void>;
  invalidateVersionInfo: () => Promise<void>;
  getVersionInfoFromCache: () => VersionInfo | undefined;
  setVersionInfoInCache: (versionInfo: VersionInfo) => void;
}

Return Value​

MethodDescription
prefetchVersionInfoPrefetch version info into the query cache (respects staleTime)
invalidateVersionInfoInvalidate the cached version data, triggering a background refetch
getVersionInfoFromCacheSynchronously read the current version info from the cache
setVersionInfoInCacheDirectly set version info in the cache (useful for optimistic updates)

Usage Examples​

import { useVersionInfo } from '@/hooks/use-version-info';

function AppFooter() {
  const { versionInfo, isLoading } = useVersionInfo();

  if (isLoading || !versionInfo) {
    return <span>Loading version...</span>;
  }

  return (
    <footer>
      <p>
        Version: {versionInfo.commit.slice(0, 7)} |
        Last updated: {new Date(versionInfo.date).toLocaleDateString()} |
        By: {versionInfo.author}
      </p>
    </footer>
  );
}

With custom refresh interval​

const { versionInfo } = useVersionInfo({
  refreshInterval: 60 * 1000, // Refresh every minute
  retryOnError: true,
});

Disable auto-fetching​

const { versionInfo, refetch } = useVersionInfo({
  enabled: false,
});

// Manually fetch when needed
const handleRefresh = () => refetch();

Prefetch on layout mount​

import { useVersionInfoUtils } from '@/hooks/use-version-info';

function AppLayout({ children }) {
  const { prefetchVersionInfo } = useVersionInfoUtils();

  useEffect(() => {
    prefetchVersionInfo();
  }, [prefetchVersionInfo]);

  return <main>{children}</main>;
}

Read version from cache without triggering a fetch​

import { useVersionInfoUtils } from '@/hooks/use-version-info';

function DebugPanel() {
  const { getVersionInfoFromCache } = useVersionInfoUtils();
  const cached = getVersionInfoFromCache();

  return cached
    ? <pre>{JSON.stringify(cached, null, 2)}</pre>
    : <p>No version info in cache</p>;
}

Requirements​

DependencyPurpose
@tanstack/react-queryQuery caching, refetching, and retry logic
@/lib/api/server-api-clientserverClient for making API requests, apiUtils for response handling
/api/versionServer endpoint that returns VersionInfo data