effect-api-query

Use Effect RPC and HttpApi with typed TanStack Query options and semantic cache keys.

Create utilities from your API definition and a ready client, then pass their options directly to TanStack Query. Your application controls the client lifetime, cache policies, and framework setup.

Install

pnpm add effect-api-query @tanstack/query-core

With automatic peer installation enabled, pnpm installs the exact Effect version declared by the package. Use TypeScript 5.9 or newer with strict: true. The package requires ESM and ES2022 support. Before upgrading, review compatibility and stability.

Query an RPC

Pass your RPC group and ready flat client to the factory:

import { createRpcQueryUtils } from 'effect-api-query'

const rpc = createRpcQueryUtils(rpcGroup, {
  client,
  keyPrefix: ['my-app'],
  runPromiseExit,
})

const options = rpc.users.get.queryOptions({ input: { id: 1 } })
const user = await queryClient.query(options)

Follow the RPC quick start for setup and cleanup.

Query an HttpApi

Pass your HttpApi declaration and ready HTTP API client to the factory:

import { createHttpApiQueryUtils } from 'effect-api-query'

const http = createHttpApiQueryUtils(api, {
  client: httpClient,
  keyPrefix: ['my-app'],
  runPromiseExit,
})

const options = http.users.get.queryOptions({ input: { params: { id: 1 } } })
const user = await queryClient.query(options)

HTTP accepts decoded request parts; RPC accepts payload constructor input. Follow the HTTP quick start for a complete declaration, client, query, and mutation.

Choose an operation

API definition	Available operations
Unary RPC	Queries, infinite queries, and mutations
Streaming RPC	Accumulated streamed queries and live queries
Buffered HttpApi endpoint without multipart	Queries, infinite queries, and mutations
Buffered HttpApi endpoint with multipart	Mutations with FormData

Both factories generate keys for cache reads, writes, prefetching, and invalidation. Query functions forward cancellation to Effect. Mutations use TanStack's normal callbacks; invalidate affected queries in your application.

For uploads, build FormData explicitly and pass it as mutation payload. See the HTTP upload guide. Streaming HTTP responses and streaming multipart requests remain omitted.

Integrate with your application

• React Query: use generated options with hooks.
• TanStack Start: share RPC and HTTP options across loaders, server rendering, and hydration.
• Run the examples: try complete Vite React and TanStack Start applications.
• Feature support: check available operations and integration limits.
• API reference: look up factories, builders, and errors.

Agent skill

Install the library usage skill from this repository:

npx skills add ueberBrot/effect-api-query --skill effect-api-query

The same skill ships in the npm package. With the library installed, run npx @tanstack/intent@latest install and enable effect-api-query, then load it with:

npx @tanstack/intent@latest load effect-api-query#effect-api-query

Intent reads the skill from the installed library version. Skills installed from GitHub are updated separately through the Skills CLI.