ClickHouse React
Use ClickHouse in React with typed hooks instead of custom fetch glue
This page starts where the server pages stop. The query already exists on the backend. The React problem is how components consume it without rebuilding request helpers, cache logic, and response types over and over.
Client layer
@hypequery/react
Caching
TanStack Query
Best for
Interactive dashboards
Components keep growing their own request wrappers
A dashboard starts with one chart and quickly becomes a stack of `fetch`, loading state, error handling, cache invalidation, and manually typed response objects.
The browser should not own analytics schema details
The UI should not need to know about ClickHouse return types or how backend query code is assembled. It should call a typed API surface and render what comes back.
Client typing drifts when it is maintained separately
Once the React layer starts owning its own request and response types, changes show up as UI bugs rather than compiler errors.
The client-side shape
Derive hooks from the server API instead of recreating it
The clean React model is straightforward: keep analytics on the server, expose a typed API, and let the hook layer inherit that type so components stay focused on UI behavior.
- Keep ClickHouse access and schema knowledge on the server
- Infer hook types directly from the serve API
- Use TanStack Query for cache lifecycle and background refetching
- Share one query contract across charts, tables, and filters
- Avoid manually duplicating request and response types in React
Hook setup
One hook layer for the whole React app
This is the boundary worth preserving. The hook layer learns from the API type rather than inventing its own client-side contract.
Dashboard usage
Let components deal with UI state, not transport details
Once the hooks exist, a component can ask for a named query and render it. That keeps the React layer concerned with charts, filters, and interaction instead of transport details.
This pays off quickly in dashboards where several panels share filters and revalidation rules. TanStack Query handles the browser lifecycle while the backend still owns the actual analytics definition.
If your main concern is App Router delivery and server components, use the Next.js page. This page is specifically about the client hook layer.
Component
A chart component that only consumes a typed hook
The component does not import ClickHouse types or know about SQL. It consumes the typed hook and renders UI state.
Where teams usually get stuck
The questions this page should answer
What this page replaces
It replaces component-level fetch helpers and hand-written hook wrappers that slowly diverge from the backend response shape.
Where React should stop
The React layer should own cache behavior and UI state, not ClickHouse details or backend schema assumptions.
What makes the typing trustworthy
The hook types are useful because they are derived from the backend API definition, which is itself derived from the query layer.
Where to branch next
Use the Next.js page for local server execution versus HTTP delivery. Use this page when the hook layer itself is the thing you are designing.
Further reading
Go deeper where it actually helps
React getting started
Set up the hook layer and provider wiring.
Open guide
Advanced React patterns
Handle method configuration, invalidation, and richer client workflows.
Open guide
ClickHouse Next.js
Pair React hooks with App Router and server-side execution.
Open guide
Turn your ClickHouse schema into a type-safe analytics layer
See the full path from schema generation to hooks.
Open guide
Next step
Set up typed hooks on top of a shared server definition
Do not start by inventing a browser-only analytics client. Start from the server API type, then let the React layer inherit it.