React Hooks - Getting Started

Use @hypequery/react to generate type-safe hooks (useQuery, useMutation) backed by TanStack Query. Bring your exported serve({ queries }) API type into your React app without duplicating schemas.

For semantic metrics and datasets endpoints, use createAnalyticsHooks, which adds useMetric and useDataset on top of the base hooks. See Analytics hooks for metrics and datasets below.

Installation

npm install @hypequery/react @tanstack/react-query

Peer dependencies: react@^18, @tanstack/react-query@^5.

Setup

Option 1: Automatic Type Inference (Recommended)

Use InferApiType to automatically extract types from your API definition:

// lib/analytics.ts
import { createHooks } from '@hypequery/react';
import { InferApiType } from '@hypequery/serve';
import type { api } from '@/analytics/queries';

// Automatic type inference - no manual type definition needed!
type Api = InferApiType<typeof api>;

export const { useQuery, useMutation } = createHooks<Api>({
  baseUrl: '/api', // where your hypequery routes live
});

This eliminates the need to manually define and maintain a separate type for your API.

Option 2: Manual Type Definition

If you prefer to manually define your API types:

// lib/analytics.ts
import { createHooks } from '@hypequery/react';

type Api = {
  weeklyRevenue: {
    input: { startDate: string };
    output: { total: number };
  };
  // ... other queries
};

export const { useQuery, useMutation } = createHooks<Api>({
  baseUrl: '/api',
});

Analytics hooks for metrics and datasets

When your API registers metrics or datasets, use createAnalyticsHooks instead of createHooks. It returns everything createHooks does, plus useMetric, useDataset, useInfiniteMetric, and useInfiniteDataset.

Semantic endpoints are POST routes whose paths differ from their map keys (e.g. the orders dataset lives at POST /datasets/orders/query). Pass a manifest from the serve API's api.manifest() so the hooks can resolve those routes:

// lib/analytics.ts
import { createAnalyticsHooks } from '@hypequery/react';
import { InferApiType } from '@hypequery/serve';
import { api } from '@/analytics/queries';

type Api = InferApiType<typeof api>;

export const {
  useQuery,
  useMutation,
  useMetric,
  useDataset,
  useInfiniteMetric,
  useInfiniteDataset,
} = createAnalyticsHooks<Api>({
  baseUrl: '/api',
  // Required for metric/dataset endpoints — resolves each key's method + path.
  manifest: api.manifest(),
});

api.manifest() is safe to JSON-serialize, so you can also fetch it from a small endpoint at runtime when your client can't import the server module — see Auto-config from server. Without a manifest (or an explicit config entry), useMetric/useDataset throw a clear error rather than calling the wrong URL.

Provider Setup

Wrap your app with TanStack Query's provider:

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

export function AppProviders({ children }: { children: React.ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      {children}
    </QueryClientProvider>
  );
}

// app.tsx or _app.tsx
import { AppProviders } from './providers';

function App() {
  return (
    <AppProviders>
      <YourApp />
    </AppProviders>
  );
}

Getting Started