Introduction

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

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

For AI Agents

If you're an AI agent integrating kitcn, ask the user to select their stack before starting. Use your AskUserQuestion tool (or equivalent) to let them pick:

Required Choices

Optional Features

After Selection

CLI bootstrap:

1. Run kitcn init -t next --yes for the shortest fresh local Convex path.
2. Add only the features you chose with kitcn add <plugin>:
   • kitcn add auth
   • kitcn add ratelimit
   • kitcn add resend
3. On backend convex, init and dev run convex init before kitcn codegen.
4. Use kitcn verify for a one-shot local runtime proof in the current app. Use kitcn dev --bootstrap when you specifically want one-shot local setup. During local Convex dev, convex/.env edits auto-sync. kitcn add auth --yes also finishes local auth bootstrap in one pass. Use kitcn env push for --prod, --rotate, or explicit repair against an active deployment.
5. Use kitcn insights when you need the upstream Convex insights view from the same CLI entrypoint.
6. If browser smoke says use http://localhost:3000 but port 3000 is occupied, run smoke on the actual dev server port instead and note it in the report.

Docs-by-section approach:

1. Follow Quickstart for initial setup
2. Read individual docs for each feature needed
3. Use CLI Registry as the bootstrap reference
4. Confirm deployment/bootstrap is configured before relying on generated imports

Quick Reference by Stack

Documentation Map

Getting Started

Server (Backend)

Plugins

Database

React (Client)

Next.js

Auth (Better Auth)

Reference

Common Workflows

New project setup:

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

Add authentication:

1. Auth Server → configure Better Auth
2. Auth Client → use auth in components
3. Middlewares → protect procedures

Add database features:

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

Server components (RSC):

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