@gencow/react

React hooks for Gencow — useQuery, useMutation, GencowProvider, useAuth.

Release policy: Keep version in sync with @gencow/client. Publish client and react together on every release (same semver).

Install

npm install @gencow/client @gencow/react

Typed defineQuery / defineMutation in generated api.ts come from @gencow/client. Auth client (createAuthClient) lives in @gencow/client; this package adds React hooks including useAuth.

Quick Start

// src/lib/auth.ts
import { createAuthClient } from "@gencow/client";

export const auth = createAuthClient("http://localhost:5456");
// XSS-sensitive apps — keep the refresh session token out of localStorage:
// createAuthClient("http://localhost:5456", { strategy: { kind: "token", sessionTokenStorage: "memory" } })
export const { signIn, signUp, signOut } = auth;

// src/main.tsx
import { GencowProvider } from "@gencow/react";
import { auth } from "./lib/auth";

export default function Layout({ children }) {
    return (
        <GencowProvider baseUrl="http://localhost:5456" auth={auth}>
            {children}
        </GencowProvider>
    );
}

Hooks

useQuery — 실시간 데이터 구독

import { useQuery } from "@gencow/react";
import { api } from "@/gencow/api";

const { data: tasks, isLoading, isFetching } = useQuery(api.tasks.list);
const { data: task } = useQuery(api.tasks.get, { id: 1 });  // Task | undefined

• isLoading === true = 첫 fetch 중이고 아직 표시할 data가 없음
• isFetching === true = 첫 fetch 또는 기존 data가 있는 background refetch 진행 중
• WebSocket으로 서버가 데이터 변경 시 자동 갱신
• 에러 발생 시 error 필드로 확인 가능

조건부 쿼리 (skip/enabled)

// 방법 A: "skip" 토큰 (Convex 스타일) — 추천
const { data: messages } = useQuery(api.chat.getMessages,
    conversationId ? { conversationId } : "skip"
);

// 방법 B: enabled 옵션 (TanStack Query 스타일)
const { data: messages } = useQuery(api.chat.getMessages,
    { conversationId },
    { enabled: !!conversationId }
);
// → skip 상태에서는 API 호출 없이 data=undefined, isLoading=false

useMutation — 데이터 변경

import { useMutation } from "@gencow/react";

const { mutate: create, isPending, error } = useMutation(api.tasks.create);
await create({ title: "새 태스크" });
// → 서버가 WebSocket으로 useQuery를 자동 갱신

useStatus — WebSocket 연결 상태

import { useStatus } from "@gencow/react";

const { isConnected } = useStatus();

Auth

Create the client with @gencow/client, pass it to GencowProvider, and read session state with useAuth from this package:

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

export const auth = createAuthClient();
export const { signIn, signUp, signOut } = auth;

// Keep the refresh-style session token out of localStorage:
// createAuthClient(undefined, { strategy: { kind: "token", sessionTokenStorage: "memory" } })

await signIn("[email protected]", "password");

// Inside a component under <GencowProvider auth={auth}>:
const { token, user, isAuthenticated } = useAuth();

License

MIT