Introduction

A complete framework for building type-safe, real-time applications with Convex.

Introduction

kitcn is a complete framework for Convex. It brings tRPC-style APIs, TanStack Query, a Drizzle-style ORM, and Better Auth into one cohesive developer experience.

This is not just a query wrapper. It's how you build production Convex applications.

Philosophy

kitcn integrates Convex for realtime data, TanStack Query for caching, and Better Auth for authentication behind a consistent API:

Type safety end-to-end - From schema to procedures to client, with full inference
Real-time by default - WebSocket subscriptions flow into TanStack Query cache
TanStack Query native - Use useQuery and useMutation directly with cRPC options
Incremental adoption - Add features as you need them, migrate function by function

What's Included

Export	Description	Depends on
`kitcn` (CLI)	Codegen, `kitcn dev`	—
`kitcn/server`	cRPC builder, middleware, server caller	—
`kitcn/orm`	Drizzle-style ORM schema and query helpers	—
`kitcn/react`	React client, providers, auth hooks	`server`
`kitcn/rsc`	RSC prefetching, hydration	`server`, `react`, `next`
`kitcn/auth`	Better Auth adapter	—
`kitcn/auth/client`	Better Auth client plugins	`react`
`kitcn/auth/config`	Convex auth config provider	`auth`
`kitcn/auth/http`	Auth HTTP helpers	`auth`
`kitcn/auth/nextjs`	Better Auth Next.js adapter	`server`, `next`
`kitcn/auth/start`	Better Auth TanStack Start adapter	`auth`
`kitcn/ratelimit`	Rate limiting plugin	`orm`

server, orm, and auth are standalone foundations — everything else builds on one or more. You can use server or auth without orm, orm and plugins without server.

Quick Look

// Server: Define a procedure
export const list = authQuery
  .input(z.object({ limit: z.number().optional() }))
  .query(async ({ ctx, input }) => {
    return ctx.orm.query.posts.findMany({ limit: input.limit ?? 10 });
  });

// Client: Use it with TanStack Query
const { data: posts } = useQuery(crpc.posts.list.queryOptions({ limit: 10 }));

Requirements

Convex 1.31+
TanStack Query 5+
React 18+

Next Steps

Quickstart

CLI

Concepts

For AI Agents

Ask the user to select their stack before starting:

Required Choices

Feature	Options	Default
Bootstrap	CLI (`kitcn init` / `add`), Docs by section	CLI
React Framework	Next.js App Router, TanStack Start, Vite	Next.js App Router
Database	ORM (`ctx.orm`)	ORM

Optional Features

Feature	Options	When to Include
Auth	Better Auth, Custom, None	Most apps need auth
SSR/RSC	Yes, No	Next.js App Router apps
Triggers	Yes, No	Auto side effects on data changes
Aggregates	Yes, No	Counts, sums, leaderboards
Rate Limiting	Yes, No	API protection
Scheduling	Yes, No	Delayed/background work
HTTP router	Yes, No	REST/webhook endpoints
RLS	Yes, No	Runtime row-level access control
Auth plugins	admin, organizations, polar, none	Only when required by product

CLI Bootstrap

Scaffold:
- Next.js: npx kitcn@latest init -t next --yes
- TanStack Start: npx kitcn@latest init -t start --yes
- Vite: npx kitcn@latest init -t vite --yes
- Expo: npx kitcn@latest init -t expo --yes
Add features with kitcn add <plugin>:
- npx kitcn add auth --yes
- npx kitcn add ratelimit --yes
- npx kitcn add resend --yes
Run: npx kitcn dev (runs convex init + codegen + watchers)
Verify: npx kitcn verify (one-shot local runtime proof, stop kitcn dev first)
Env: backend convex uses npx kitcn env push for --prod, --rotate, or explicit repair. backend concave uses npx kitcn auth jwks for manual JWKS export. During local Convex dev, convex/.env edits auto-sync.
Local auth assumes http://localhost:3000. If you change the port, update SITE_URL in convex/.env and the matching client env var (NEXT_PUBLIC_SITE_URL for Next.js, VITE_SITE_URL for Start/Vite, EXPO_PUBLIC_SITE_URL for Expo).

Docs-by-Section Bootstrap

Follow Quickstart
Read individual docs for each feature
Use CLI Registry as the command reference
Confirm deployment/bootstrap before relying on generated imports

Quick Reference by Stack

Stack	Key Docs
Next.js + Auth	Quickstart, Next.js, Auth Server
TanStack Start + Auth	TanStack Start, Auth Server
Vite + No Auth	React Setup, Server Setup
Expo + Auth	Expo, Auth Server
Expo + No Auth	Expo, Server Setup
Any + Custom Auth	Server Setup, Middlewares

Documentation Map

Getting Started

Page	When to Use
Quickstart	First-time setup. Follow step-by-step to get a working app.
Concepts	Understand architecture, folder structure (`convex/functions/`, `convex/lib/`, `convex/shared/`), and design decisions.
CLI Registry	Bootstrap new or existing apps with `kitcn init`, add features with `kitcn add`, and inspect plans with `view`, `info`, and `docs`.

Server (Backend)

Page	When to Use
Server Setup	Initialize cRPC builder with `initCRPC`. Configure `dataModel`, `context`, `meta`.
Procedures	Define queries, mutations, actions with `.input()`, `.output()`, `.query()/.mutation()/.action()`. Paginated queries with `.paginated()`.
Context	Extend context with `ctx.orm`, `ctx.auth`. Add custom properties via `.context()`.
Middlewares	Create reusable middleware with `.use()`. Auth guards, logging, rate limiting. Chain with `.pipe()`.
Metadata	Add procedure metadata with `.meta()`. Used by CLI for auth-aware query handling.
Error Handling	Throw `CRPCError` with codes like `UNAUTHORIZED`, `NOT_FOUND`, `BAD_REQUEST`.
Server-Side Calls	Call procedures from server with `createCallerFactory`. RSC data fetching.
Scheduling	Run cron jobs and one-time background work with Convex scheduler APIs.

Plugins

Page	When to Use
Plugins	Discover cross-cutting features that span schema, runtime, and client DX.
Rate Limiting	Add token bucket and fixed/sliding window rate limiting with `kitcn/ratelimit`.

Database

Page	When to Use
ORM	Drizzle-style schema, queries, mutations, RLS, runtime constraints via `ctx.orm`.
Triggers	Automatic side effects on insert/update/delete with schema triggers.
Aggregates	Scalar metrics (`count`, `aggregate`) and ranked aggregate runtime.

React (Client)

Page	When to Use
React Setup	Configure providers: `QueryClientProvider`, `CRPCProvider`. Singleton helpers.
Queries	`useQuery` with `crpc.path.queryOptions()`. Real-time updates, `skipToken` for conditional queries.
Mutations	`useMutation` with `crpc.path.mutationOptions()`. Toast patterns, optimistic updates.
Infinite Queries	`useInfiniteQuery` with `crpc.path.infiniteQueryOptions()`. Cursor-based pagination.
Type Inference	`inferApiInputs`, `inferApiOutputs` for tRPC-style type extraction.
Error Handling	Handle `CRPCClientError` on client. Error boundaries, toast notifications.

Next.js

Page	When to Use
Next.js Setup	Configure `convexBetterAuth` for RSC. Server caller factory, JWT caching.
RSC	Server components with `prefetch`, `preloadQuery`, `HydrateClient`. SSR data fetching.

Auth (Better Auth)

Page	When to Use
Auth Overview	Architecture overview. When to use Better Auth vs other auth solutions.
Auth Server	Complete Better Auth setup: schema, adapters, HTTP routes, helpers.
Auth Client	`useAuth`, `Authenticated`/`Unauthenticated` components.

Reference

Page	When to Use
CLI Backend	`kitcn dev` for codegen. Procedure metadata generation.
Migrations	Migration hub with paths for Core, ORM, and Auth.
Comparison	Compare with tRPC, Convex hooks, other patterns.

Common Workflows

New project setup:

Quickstart → basic setup
CLI Registry → use kitcn init for scaffolding or adoption, and kitcn add for feature layers
Concepts → understand folder structure

Add authentication:

Auth Server → configure Better Auth
Auth Client → use auth in components
Middlewares → protect procedures

Add database features:

ORM → schema + queries via ctx.orm
Triggers → automatic side effects
Aggregates → counts and sums

Server components (RSC):

Next.js Setup → configure caller
RSC → prefetch and hydrate

Introduction

Quickstart

CLI

Concepts

On this page