kitcn 0.0.1 → 0.12.1

package/skills/convex/references/setup/next.md

@@ -0,0 +1,116 @@
+## 8. Framework-Specific Setup
+
+## 8.A Next.js App Router
+
+### 8.A.1 Server caller + auth utilities
+
+**Create:** `src/lib/convex/server.ts`
+
+```ts
+import { api } from "@convex/api";
+import { convexBetterAuth } from "kitcn/auth/nextjs";
+
+export const { createContext, createCaller, handler } = convexBetterAuth({
+  api,
+  convexSiteUrl: process.env.NEXT_PUBLIC_CONVEX_SITE_URL!,
+});
+```
+
+### 8.A.2 Auth API route
+
+**Create:** `src/app/api/auth/[...all]/route.ts`
+
+```ts
+import { handler } from "@/lib/convex/server";
+
+export const { GET, POST } = handler;
+```
+
+### 8.A.3 RSC helpers
+
+**Create:** `src/lib/convex/rsc.tsx`
+
+```tsx
+import "server-only";
+
+import { api } from "@convex/api";
+import type { FetchQueryOptions } from "@tanstack/react-query";
+import {
+  dehydrate,
+  HydrationBoundary,
+  QueryClient,
+} from "@tanstack/react-query";
+import {
+  createServerCRPCProxy,
+  getServerQueryClientOptions,
+} from "kitcn/rsc";
+import { headers } from "next/headers";
+import { cache } from "react";
+
+import { hydrationConfig } from "./query-client";
+import { createCaller, createContext } from "./server";
+
+const createRSCContext = cache(async () =>
+  createContext({ headers: await headers() })
+);
+
+export const caller = createCaller(createRSCContext);
+export const crpc = createServerCRPCProxy({ api });
+
+function createServerQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      ...hydrationConfig,
+      ...getServerQueryClientOptions({
+        getToken: caller.getToken,
+        convexSiteUrl: process.env.NEXT_PUBLIC_CONVEX_SITE_URL!,
+      }),
+    },
+  });
+}
+
+export const getQueryClient = cache(createServerQueryClient);
+
+export function prefetch<T extends { queryKey: readonly unknown[] }>(
+  queryOptions: T
+): void {
+  void getQueryClient().prefetchQuery(queryOptions);
+}
+
+export function preloadQuery<
+  TQueryFnData = unknown,
+  TError = Error,
+  TData = TQueryFnData,
+  TQueryKey extends readonly unknown[] = readonly unknown[],
+>(
+  options: FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey>
+): Promise<TData> {
+  return getQueryClient().fetchQuery(options);
+}
+
+export function HydrateClient({ children }: { children: React.ReactNode }) {
+  const queryClient = getQueryClient();
+  const dehydratedState = dehydrate(queryClient);
+
+  return (
+    <HydrationBoundary state={dehydratedState}>{children}</HydrationBoundary>
+  );
+}
+```
+
+### 8.A.4 Pass server token to provider
+
+```tsx
+// app/(app)/layout.tsx
+import { AppConvexProvider } from "@/lib/convex/convex-provider";
+import { caller } from "@/lib/convex/rsc";
+
+export default async function AppLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const token = await caller.getToken();
+  return <AppConvexProvider token={token}>{children}</AppConvexProvider>;
+}
+```

package/skills/convex/references/setup/react.md

@@ -0,0 +1,175 @@
+## 7. Client Core (after auth gate)
+
+### 7.1 Auth client setup
+
+Prerequisite:
+
+1. Section 6.10 / Section 11.3 auth sign-in gate is green.
+
+**Create:** `src/lib/convex/auth-client.ts`
+
+```ts
+import type { Auth } from "@convex/auth-shared";
+import { adminClient, inferAdditionalFields } from "better-auth/client/plugins";
+import { createAuthClient } from "better-auth/react";
+import { convexClient } from "kitcn/auth/client";
+import { createAuthMutations } from "kitcn/react";
+
+export const authClient = createAuthClient({
+  baseURL: process.env.NEXT_PUBLIC_SITE_URL!,
+  sessionOptions: {
+    // Disable session polling on tab focus (saves ~500ms HTTP call per focus)
+    refetchOnWindowFocus: false,
+  },
+  plugins: [inferAdditionalFields<Auth>(), adminClient(), convexClient()],
+});
+
+export const { useActiveOrganization, useListOrganizations } = authClient;
+
+export const {
+  useSignOutMutationOptions,
+  useSignInSocialMutationOptions,
+  useSignInMutationOptions,
+  useSignUpMutationOptions,
+} = createAuthMutations(authClient);
+```
+
+### 7.2 QueryClient setup
+
+**Create:** `src/lib/convex/query-client.ts`
+
+```ts
+import {
+  type DefaultOptions,
+  defaultShouldDehydrateQuery,
+  QueryCache,
+  QueryClient,
+} from "@tanstack/react-query";
+import { isCRPCClientError, isCRPCError } from "kitcn/crpc";
+import SuperJSON from "superjson";
+
+export const hydrationConfig: Pick<DefaultOptions, "dehydrate" | "hydrate"> = {
+  dehydrate: {
+    serializeData: SuperJSON.serialize,
+    shouldDehydrateQuery: (query) =>
+      defaultShouldDehydrateQuery(query) || query.state.status === "pending",
+    shouldRedactErrors: () => false,
+  },
+  hydrate: {
+    deserializeData: SuperJSON.deserialize,
+  },
+};
+
+export function createQueryClient() {
+  return new QueryClient({
+    queryCache: new QueryCache({
+      onError: (error) => {
+        if (isCRPCClientError(error)) {
+          console.warn(`[CRPC] ${error.code}:`, error.functionName);
+        }
+      },
+    }),
+    defaultOptions: {
+      ...hydrationConfig,
+      queries: {
+        retry: (failureCount, error) => {
+          if (isCRPCError(error)) return false;
+          return failureCount < 3;
+        },
+      },
+    },
+  });
+}
+```
+
+### 7.3 cRPC React context
+
+**Create:** `src/lib/convex/crpc.tsx`
+
+Preconditions:
+
+1. Complete Section 5.5 first so `@convex/api` exists.
+2. Complete Section 7.4 so `CRPCProvider` is mounted before any `useCRPC()` call.
+
+```tsx
+import { api } from "@convex/api";
+import { createCRPCContext } from "kitcn/react";
+
+export const { CRPCProvider, useCRPC, useCRPCClient } = createCRPCContext({
+  api,
+  convexSiteUrl: process.env.NEXT_PUBLIC_CONVEX_SITE_URL!,
+});
+```
+
+### 7.4 Provider composition
+
+**Create:** `src/lib/convex/convex-provider.tsx`
+
+Hard rule:
+
+1. Any component using `useCRPC`, `useCRPCClient`, or cRPC hooks must render under `CRPCProvider`.
+2. If not, runtime will crash with `useCRPC must be used within CRPCProvider`.
+
+```tsx
+"use client";
+
+import { QueryClientProvider as TanstackQueryClientProvider } from "@tanstack/react-query";
+import { ConvexAuthProvider } from "kitcn/auth/client";
+import {
+  ConvexReactClient,
+  getConvexQueryClientSingleton,
+  getQueryClientSingleton,
+  useAuthStore,
+} from "kitcn/react";
+import type { ReactNode } from "react";
+
+import { authClient } from "./auth-client";
+import { CRPCProvider } from "./crpc";
+import { createQueryClient } from "./query-client";
+
+const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
+
+export function AppConvexProvider({
+  children,
+  token,
+}: {
+  children: ReactNode;
+  token?: string;
+}) {
+  return (
+    <ConvexAuthProvider
+      authClient={authClient}
+      client={convex}
+      initialToken={token}
+    >
+      <QueryProvider>{children}</QueryProvider>
+    </ConvexAuthProvider>
+  );
+}
+
+function QueryProvider({ children }: { children: ReactNode }) {
+  const authStore = useAuthStore();
+
+  const queryClient = getQueryClientSingleton(createQueryClient);
+  const convexQueryClient = getConvexQueryClientSingleton({
+    authStore,
+    convex,
+    queryClient,
+  });
+
+  return (
+    <TanstackQueryClientProvider client={queryClient}>
+      <CRPCProvider convexClient={convex} convexQueryClient={convexQueryClient}>
+        {children}
+      </CRPCProvider>
+    </TanstackQueryClientProvider>
+  );
+}
+```
+
+Provider mount checklist:
+
+1. `AppConvexProvider` wraps app routes before client feature components render.
+2. `CRPCProvider` is nested inside TanStack Query provider (`QueryClientProvider`).
+3. Next.js apps pass token where required (Section 8.A.4) or intentionally run without token for public-only paths.
+