Client SDK

@gencow/client — runtime behind codegen and @gencow/react (not imported in typical app code)

@gencow/client is the framework-agnostic runtime Gencow installs as a dependency. Application code does not import it directly in the usual flow — gencow codegen writes gencow/api.ts with imports from @gencow/client, and `@gencow/react` hooks call those generated defs. Install it alongside @gencow/react; import hooks and api in your app, not @gencow/client procedure helpers.

npm install @gencow/client

For React apps, also install @gencow/react:

npm install @gencow/client @gencow/react

Versions: @gencow/client and @gencow/react share the same semver and are published together.

Choose your stack

Experimental: `@gencow/tanstack-query` is not stable yet — APIs and codegen output may change before a non-experimental release.

Generated api.ts

gencow dev / gencow codegen emits gencow/api.ts (or src/gencow/api.ts) with imports from @gencow/client:

import { defineProcedureQuery, defineProcedureMutation } from "@gencow/client";
import type * as Operations from "./operations.d.ts";

export const api = {
  tasks: {
    list: defineProcedureQuery<Operations.TasksListOutput>("tasks.list", { allowAnonymous: true }),
    create: defineProcedureMutation<Operations.TasksCreateOutput>("tasks.create"),
  },
} as const;

Do not edit this file manually. Codegen adds the @gencow/client imports; your app imports api and (for React) hooks from @gencow/react.

Runtime client (createGencowClient)

Bundle your generated api, baseUrl, and auth into one framework-agnostic client. Use it for imperative calls (SSR, scripts) and as the input to React or TanStack setup:

// src/lib/apiClient.ts
import { createGencowClient } from "@gencow/client";
import { api } from "../gencow/api";
import { auth } from "./auth";

const baseUrl = import.meta.env.VITE_API_URL;

export const apiClient = createGencowClient({ api, baseUrl, auth });

// Outside React — no provider required
const tasks = await apiClient.call.query(api.tasks.list, {});

SSR / scripts: apiClient.call.* does not require a React provider, but protected procedures often return 401 unless the request can send credentials. In the browser, auth can read a stored token or cookie; on the server or in a one-off script you usually have neither unless you explicitly forward the session (cookie header, bearer token from the incoming request, etc.). Use { public: true } only for endpoints your API allows anonymously, or pass auth context into that environment first.

React apps pass apiClient to `<GencowProvider apiClient={apiClient}>`. TanStack apps build `tanstackApi` from the same apiClient and mount `GencowTanstackProvider` only — do not nest both providers.

Auth (no React)

import { createAuthClient } from "@gencow/client";

export const auth = createAuthClient(import.meta.env.VITE_API_URL);

await auth.signIn("[email protected]", "password");
const state = auth.store.getState();

React apps read session state with `useAuth()` from @gencow/react (under GencowProvider or GencowTanstackProvider).

Realtime helpers (internal)

buildQuerySubscriptionKey, createInvalidationRefetchScheduler, and authorizeRealtimeQuery live in @gencow/client for @gencow/react hooks (for example useQuery({ realtime: true })). Do not import them in application code.

Procedure RPC (internal)

The procedure wire codec (@gencow/client/procedure-rpc) is not for application imports. Generated api.ts uses it indirectly through defineProcedureQuery / defineProcedureMutation; the server uses the same codec for unified RPC routes. @gencow/react/procedure-rpc is deprecated and only re-exports @gencow/client/procedure-rpc for legacy tooling.

Next Steps

• React Hooks — GencowProvider, useQuery, useMutation
• TanStack Query — GencowTanstackProvider, createTanstackQueryApiClient (experimental)
• Core API — Backend procedure, createCrud, schema
• Queries Guide — Using useQuery with generated api