### Installation and Environment Variables for Quickstart

Source: https://github.com/udecode/kitcn/blob/main/docs/plans/2026-01-23-fix-quickstart-documentation-gaps-plan.md

Example of adding dependencies and environment variables to the quickstart documentation, including conditional setup for ctx.db and ctx.table.

```diff
## Installation

```bash
bun add convex kitcn convex-helpers zod @tanstack/react-query
```

+<Tabs groupId="db" items={["ctx.db", "ctx.table"]} persist>
+  <Tab value="ctx.db">
+    That's all you need for the standard flow.
+  </Tab>
+  <Tab value="ctx.table">
+    For Convex Ents (ctx.table), also install:
+    ```bash
+    bun add convex-ents
+    ```
+  </Tab>
+</Tabs>

+## Environment Variables
+
+Create `.env.local` with your Convex URLs:
+
+```bash title=".env.local"
+NEXT_PUBLIC_CONVEX_URL=http://localhost:3210
+NEXT_PUBLIC_CONVEX_SITE_URL=http://localhost:3211
+```

+## Create Ents Helper (ctx.table only)
+
+<Tabs groupId="db" items={["ctx.db", "ctx.table"]} persist>
+  <Tab value="ctx.db">
+    Skip this step - you'll use `ctx.db` directly.
+  </Tab>
+  <Tab value="ctx.table">
+    Create the ents helper to enable `ctx.table`:
+
+    ```ts title="convex/lib/ents.ts"
+    // [full ents.ts content]
+    ```
+  </Tab>
+</Tabs>

+## Create Shared Types
+
+Create the type utilities for client-side type inference:
+
+```ts title="convex/shared/api.ts"
+import type { api } from '../functions/_generated/api';
+
+export type Api = typeof api;
+```
+
+<Callout icon={<InfoIcon />}>
+When you add HTTP routes later, update this to use `WithHttpRouter`. See [Templates](/docs/templates#typests).
+</Callout>
```

--------------------------------

### Start Application

Source: https://github.com/udecode/kitcn/blob/main/example/README.md

Starts the application and Convex processes.

```bash
bun --cwd /Users/zbeyens/GitHub/kitcn/example dev
```

--------------------------------

### Start the Next.js development server

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/quickstart.mdx

Starts the Next.js development server for the frontend application.

```bash
npm run dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/udecode/kitcn/blob/main/example/README.md

Installs dependencies from the repository root.

```bash
bun install
```

--------------------------------

### Component composition rule example

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/setup/server.md

Example of registering components in a `defineApp` file.

```typescript
import { defineApp } from "convex/server";
import myComponent from "some-component/convex.config";

const app = defineApp();

app.use(myComponent);

export default app;
```

--------------------------------

### Add command examples

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/cli/registry.mdx

Examples of using the `add` command to install feature layers.

```bash
npx kitcn add auth --yes
npx kitcn add auth --schema --yes
npx kitcn add ratelimit --yes
npx kitcn add resend --yes
```

--------------------------------

### example/.env.example

Source: https://github.com/udecode/kitcn/blob/main/docs/plans/2026-01-23-fix-quickstart-documentation-gaps-plan.md

Placeholder environment variables for the example project configuration.

```bash
NEXT_PUBLIC_CONVEX_URL=http://localhost:3210
NEXT_PUBLIC_CONVEX_SITE_URL=http://localhost:3211
NEXT_PUBLIC_SITE_URL=http://localhost:3000
```

--------------------------------

### Setup ORM

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/orm/queries/index.mdx

This example shows how to attach the ORM to the context, assuming it's done once.

```typescript
await ctx.orm.query.users.findMany({ limit: 10 });
```

--------------------------------

### File Organization Example

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/server/setup.mdx

Illustrates the typical file structure for organizing Convex functions and related files.

```plaintext
convex/
├── functions/
│   ├── schema.ts     # Database schema
│   ├── user.ts       # → crpc.user.list, crpc.user.create
│   ├── session.ts    # → crpc.session.getByToken
│   ├── account.ts    # → crpc.account.list, crpc.account.delete
│   └── generated/
│       ├── server.ts # Generated server contract (ORM + initCRPC)
│       └── auth.ts   # Generated auth contract
├── lib/
│   └── crpc.ts       # Setup + procedure variants
└── shared/           # Client-importable
    └── api.ts       # Generated procedure metadata
```

--------------------------------

### Singleton Helpers

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/react/index.mdx

Example of using getQueryClientSingleton to ensure consistent QueryClient instances.

```ts
const queryClient = getQueryClientSingleton(createQueryClient);

```

--------------------------------

### Install Kitcn

Source: https://github.com/udecode/kitcn/blob/main/docs/plans/2026-01-27-docs-migration-guide-from-convex-dev-better-auth-plan.md

Command to install the kitcn package.

```bash
bun add kitcn
```

--------------------------------

### Install and Run Locally

Source: https://github.com/udecode/kitcn/blob/main/tooling/scenario-fixtures/create-convex-nextjs-shadcn/README.md

Commands to install dependencies and start the development server if you have already cloned the codebase.

```bash
npm install
npm run dev
```

--------------------------------

### Install Resend Package

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/setup/server.md

Installs the necessary Resend package using bun.

```bash
bun add @kitcn/resend
```

--------------------------------

### Singleton Helpers

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/react/index.mdx

Example of using getConvexQueryClientSingleton to create and connect the ConvexQueryClient.

```ts
const convexQueryClient = getConvexQueryClientSingleton({
  convex,             // ConvexReactClient instance
  queryClient,        // TanStack QueryClient
  unsubscribeDelay,   // Optional: delay before unsubscribing (default: 3s)
});

```

--------------------------------

### Phase A Gate: Non-Auth Baseline Setup

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/setup/index.md

Commands to run after base setup and before starting authentication work.

```bash
# stop any long-running local backend first
bunx kitcn verify
bunx convex run internal.seed.seed
bunx convex run internal.init.default
# run project checks after bootstrap smoke:
bun run typecheck || bunx tsc --noEmit
bun test
bun run build
```

--------------------------------

### Admin Plugin - Client Setup

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/setup/auth.md

Example of how to set up the Admin plugin client.

```typescript
import { adminClient } from "better-auth/client/plugins";

plugins: [adminClient()];
```

--------------------------------

### cRPC builder setup

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/quickstart.mdx

This code snippet shows how to set up cRPC builders from a scaffolded cRPC file.

```typescript
import {
  initCRPC,
} from '../functions/generated/server';

const c = initCRPC.create();

export const publicQuery = c.query;
export const publicAction = c.action;
export const publicMutation = c.mutation;

export const privateQuery = c.query.internal();
export const privateMutation = c.mutation.internal();
export const privateAction = c.action.internal();
```

--------------------------------

### Your First Procedure (Before vanilla Convex)

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/server/setup.mdx

Example of defining a query procedure in vanilla Convex, using `convex/server` and `convex/values`.

```typescript
import { query } from 'convex/server';
import { v } from 'convex/values';

export const list = query({
  args: { limit: v.number() },
  handler: async (ctx, args) => {
    return ctx.db
      .query('user')
      .order('desc')
      .take(args.limit);
  },
});
```

--------------------------------

### Server Setup for TanStack Start

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/migrations/auth.mdx

Creates server-side auth helpers using `kitcn/auth/start/server` for TanStack Start.

```typescript
import { convexBetterAuthReactStart } from 'kitcn/auth/start/server';

export const { handler, getToken } = convexBetterAuthReactStart({
  convexUrl: import.meta.env.VITE_CONVEX_URL!,
  convexSiteUrl: import.meta.env.VITE_CONVEX_SITE_URL!,
});
```

--------------------------------

### Client Proxy Example

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/server/setup.mdx

Shows how the client-side proxy mirrors the server's file organization for accessing procedures.

```typescript
// File: convex/functions/user.ts, export: list
crpc.user.list.queryOptions({ limit: 10 })

// File: convex/functions/session.ts, export: getByToken
crpc.session.getByToken.queryOptions({ token: 'abc' })
```

--------------------------------

### CLI Command Example

Source: https://github.com/udecode/kitcn/blob/main/docs/solutions/integration-issues/local-convex-dev-should-watch-convex-env-20260324.md

Example of starting Convex dev with a specific backend and anonymous agent mode.

```bash
bun run convex:dev -- --backend convex
```

--------------------------------

### New TanStack Start app with the official shadcn Start shell + first local Convex bootstrap

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/setup/index.md

This command initializes a new TanStack Start app with the shadcn Start shell and local Convex bootstrap.

```bash
npx kitcn@latest init -t start --yes
```

--------------------------------

### Admin Plugin - Server Setup

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/setup/auth.md

Example of how to set up the Admin plugin on the server side.

```typescript
import { admin } from "better-auth/plugins";

plugins: [
  admin({
    defaultRole: "user",
  }),
];
```

--------------------------------

### Cloud Environment Variables

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/setup/index.md

Example environment variables for a cloud deployment of Convex.

```bash
# Generated by Convex
NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud

# Must be set manually
NEXT_PUBLIC_CONVEX_SITE_URL=https://your-project.convex.site

NEXT_PUBLIC_SITE_URL=http://localhost:3000
```

--------------------------------

### After

Source: https://github.com/udecode/kitcn/blob/main/docs/plans/2026-01-27-docs-migration-guide-from-convex-dev-better-auth-plan.md

Example of the auth.config.ts file after migration.

```typescript
import { getAuthConfigProvider } from "@convex-dev/better-auth/auth-config";
import type { AuthConfig } from "convex/server";

export default {
  providers: [getAuthConfigProvider({ jwks: process.env.JWKS })],
} satisfies AuthConfig;
```

--------------------------------

### Server Proxy

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/nextjs/index.mdx

Example of creating a cRPC proxy for Server Components.

```ts
import { createServerCRPCProxy } from 'kitcn/rsc';

// Server proxy - queryOptions only, no auth config
const crpc = createServerCRPCProxy({ api });
crpc.posts.list.queryOptions({}); // Works
crpc.posts.create.mutationOptions(); // Not available in RSC
```

--------------------------------

### Server Caller Usage Example

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/tanstack-start.mdx

Example of using `runServerCall` within a TanStack Start server function to get the current user.

```typescript
import { runServerCall } from '@/lib/convex/server';
import { createServerFn } from '@tanstack/react-start';

export const getCurrentUser = createServerFn({ method: 'GET' }).handler(
  async () => {
    return await runServerCall((caller) => caller.user.getSessionUser({}));
  },
);
```

--------------------------------

### Create and navigate to a new project directory

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/quickstart.mdx

Creates a new directory for the project and then navigates into it.

```bash
mkdir my-app
cd my-app
```

--------------------------------

### Subsection Example

Source: https://github.com/udecode/kitcn/blob/main/docs/solutions/style.md

An example of using an H3 heading for a step within a feature, starting with a guiding sentence.

```md
### Create a form schema

We'll start by defining the shape of our form using a Zod schema.
```

--------------------------------

### Pin scaffold/runtime Convex installs and set package peer ranges

Source: https://github.com/udecode/kitcn/blob/main/docs/solutions/workflow-issues/convex-135-owns-anonymous-noninteractive-setup-20260415.md

Example of how to pin Convex to an exact version for scaffold/runtime installs while setting package peer ranges at the release family floor.

```json
{
  "dependencies": {
    "convex": "1.35.1"
  },
  "peerDependencies": {
    "convex": ">=1.35"
  }
}
```

--------------------------------

### Quickstart path

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/setup/index.md

This code snippet shows the preferred bootstrap path using the CLI for a new project.

```bash
mkdir my-app
cd my-app
npx kitcn@latest init -t next --yes
```

--------------------------------

### Schema Triggers Example

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/setup/server.md

Example of defining schema triggers using `defineTriggers`.

```typescript
import { convexTable, defineTriggers, text } from "kitcn/orm";

const triggers = defineTriggers(relations, {
  post: {
    change: async (change, ctx) => {
      if (change.operation === "delete") return;
      // side effects here
    },
  },
});
```

--------------------------------

### Starter query and mutation procedures

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/quickstart.mdx

Defines a 'list' query to fetch messages and a 'create' mutation to add new messages, using Zod for input validation and output shaping.

```typescript
import { z } from 'zod';

import { publicMutation, publicQuery } from '../lib/crpc';

export const list = publicQuery
  .output(
    z.array(
      z.object({
        id: z.string(),
        body: z.string(),
        createdAt: z.date(),
      })
    )
  )
  .query(async ({ ctx }) => {
    const rows = await ctx.db.query('messages').order('desc').take(10);

    return rows.map((row) => ({
      id: row._id,
      body: row.body,
      createdAt: new Date(row._creationTime),
    }));
  });

export const create = publicMutation
  .input(z.object({ body: z.string().trim().min(1).max(120) }))
  .output(z.string())
  .mutation(async ({ ctx, input })
    await ctx.db.insert('messages', { body: input.body })
  );
```

--------------------------------

### Install Biome and Ultracite

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/setup/biome.md

Command to install Biome and Ultracite as development dependencies.

```bash
bun add -D @biomejs/biome ultracite
```

--------------------------------

### Schema Extension Contract Example

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/features/create-plugins.md

Example of how to define and install a schema extension from a plugin.

```typescript
import { defineSchema } from 'kitcn/orm';
import { myExtension } from '../lib/plugins/my-plugin/schema';

export default defineSchema(tables).extend(myExtension());

```

--------------------------------

### Get a specific environment variable

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/cli/backend.mdx

Example of getting a specific environment variable.

```bash
npx kitcn env get <name>
```

--------------------------------

### Aggregate and Rank Index Example

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/setup/server.md

Example of declaring `aggregateIndex` and `rankIndex` in table definitions.

```typescript
// convex/functions/schema.ts
const postLikes = convexTable(
  "postLikes",
  { postId: text().notNull(), userId: text().notNull() },
  (t) => [aggregateIndex("by_post").on(t.postId)]
);

const scores = convexTable(
  "scores",
  { gameId: text().notNull(), score: integer().notNull() },
  (t) => [
    rankIndex("leaderboard")
      .partitionBy(t.gameId)
      .orderBy({ column: t.score, direction: "desc" }),
  ]
);
```

--------------------------------

### Quick Start

Source: https://github.com/udecode/kitcn/blob/main/README.md

Initializes a new kitcn project with Next.js support.

```bash
npx kitcn@latest init -t next --yes
```

--------------------------------

### Install React Email Dependencies

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/setup/server.md

Installs React Email dependencies if plugins/email.tsx is selected.

```bash
bun add @react-email/components @react-email/render react-email react react-dom
```

--------------------------------

### AuthBoundary Removal Example (Before)

Source: https://github.com/udecode/kitcn/blob/main/docs/plans/2026-01-27-docs-migration-guide-from-convex-dev-better-auth-plan.md

Example of using AuthBoundary for handling authentication errors.

```typescript
import { AuthBoundary } from "@convex-dev/better-auth/react";

export const ClientAuthBoundary = ({ children }: PropsWithChildren) => {
  const router = useRouter();
  return (
    <AuthBoundary
      authClient={authClient}
      onUnauth={() => router.push("/sign-in")}
      getAuthUserFn={api.auth.getAuthUser}
      isAuthError={isAuthError}
    >
      {children}
    </AuthBoundary>
  );
};
```

--------------------------------

### src/lib/convex/crpc.tsx

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/react/index.mdx

Custom transformer example.

```tsx
import { api } from '@convex/api';
import { createTaggedTransformer } from 'kitcn/crpc';
import { createCRPCContext } from 'kitcn/react';

const transformer = createTaggedTransformer([
  // Add custom codecs here (Date is already built-in)
]);

export const { CRPCProvider, useCRPC, useCRPCClient } = createCRPCContext({
  api,
  convexSiteUrl: process.env.NEXT_PUBLIC_CONVEX_SITE_URL!,
  transformer,
});
```

--------------------------------

### Router Setup with ConvexQueryClient for TanStack Start

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/migrations/auth.mdx

Configures the router with `ConvexQueryClient` for TanStack Start.

```tsx
import { createRouter as createTanStackRouter } from '@tanstack/react-router';
import { QueryClient, notifyManager } from '@tanstack/react-query';
import { setupRouterSsrQueryIntegration } from '@tanstack/react-router-ssr-query';
import { ConvexQueryClient } from '@convex-dev/react-query';
import { routeTree } from './routeTree.gen';

export function getRouter() {
  if (typeof document !== 'undefined') {
    notifyManager.setScheduler(window.requestAnimationFrame);
  }

  const convexUrl = import.meta.env.VITE_CONVEX_URL!;

  const convexQueryClient = new ConvexQueryClient(convexUrl, {
    expectAuth: true,
  });

  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        queryKeyHashFn: convexQueryClient.hashFn(),
        queryFn: convexQueryClient.queryFn(),
      },
    },
  });
  convexQueryClient.connect(queryClient);

  const router = createTanStackRouter({
    routeTree,
    context: { queryClient, convexQueryClient },
    scrollRestoration: true,
  });

  setupRouterSsrQueryIntegration({ router, queryClient });

  return router;
}
```

--------------------------------

### Configure Environment Files

Source: https://github.com/udecode/kitcn/blob/main/example/README.md

Copies example environment files to local configuration files.

```bash
cp /Users/zbeyens/GitHub/kitcn/example/.env.example /Users/zbeyens/GitHub/kitcn/example/.env.local
cp /Users/zbeyens/GitHub/kitcn/example/convex/.env.example /Users/zbeyens/GitHub/kitcn/example/convex/.env
```

--------------------------------

### Docs command examples

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/cli/registry.mdx

Examples of using the `docs` command to get local and public doc links.

```bash
npx kitcn docs cli
npx kitcn docs auth
npx kitcn docs resend --json
```

--------------------------------

### Phase B Gate: Auth Sign-in Working Setup

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/setup/index.md

Commands to run after authentication implementation and before optional modules/plugins.

```bash
# stop any long-running local backend first
bunx kitcn verify
bun run typecheck || bunx tsc --noEmit
bun test
bun run build
```

--------------------------------

### Local Environment Variables

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/setup/index.md

Example .env.local file for setting up local Convex and application URLs.

```bash
# Convex WebSocket API
NEXT_PUBLIC_CONVEX_URL=http://localhost:3210

# Convex HTTP site URL
NEXT_PUBLIC_CONVEX_SITE_URL=http://localhost:3211

# App URL for Better Auth client
NEXT_PUBLIC_SITE_URL=http://localhost:3000
```

--------------------------------

### Get JWKS for Concave backend

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/cli/backend.mdx

Example of getting JWKS from the local default runtime for the Concave backend.

```bash
npx kitcn --backend concave auth jwks --url http://localhost:3210
```

--------------------------------

### Add command preview examples

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/cli/registry.mdx

Examples of using the `add` command with `--dry-run`, `--diff`, and `--view` flags to preview changes.

```bash
npx kitcn add resend --dry-run
npx kitcn add resend --diff convex/plugins/resend.ts
npx kitcn add resend --view convex/schema.ts
```

--------------------------------

### RLS Policy Example

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/setup/server.md

Example of defining a table with Row Level Security (RLS) policy using `rlsPolicy`.

```typescript
import { convexTable, id, rlsPolicy, text, eq } from "kitcn/orm";

export const secret = convexTable.withRLS(
  "secret",
  {
    ownerId: id("user").notNull(),
    value: text().notNull(),
  },
  (t) => [
    rlsPolicy("read_own", {
      for: "select",
      using: (ctx) => eq(t.ownerId, ctx.viewerId),
    }),
  ]
);
```

--------------------------------

### Info command examples

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/cli/registry.mdx

Examples of using the `info` command to inspect the current project state.

```bash
npx kitcn info
npx kitcn info --json
```

--------------------------------

### View command examples

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/cli/registry.mdx

Examples of using the `view` command to inspect the resolved plugin plan.

```bash
npx kitcn view auth
npx kitcn view resend --json
```

--------------------------------

### Opening Paragraph Example 1

Source: https://github.com/udecode/kitcn/blob/main/docs/solutions/style.md

An example of an opening paragraph that clearly states what the reader will learn or build in the guide.

```md
In this guide, we will take a look at building forms with React Hook Form. We'll cover building forms with the `<Field />` component, adding schema validation using Zod, error handling, accessibility, and more.
```

--------------------------------

### Demo page component

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/quickstart.mdx

This is the starter page component demonstrating the use of cRPC hooks for querying and mutating data.

```tsx
'use client';

import {
  useMutation,
  useQuery,
} from '@tanstack/react-query';
import {
  type FormEvent,
  useState,
} from 'react';

import {
  Button,
} from '@/components/ui/button';
import {
  useCRPC,
} from '@/lib/convex/crpc';

export default function ConvexMessagesPage() {
  const crpc = useCRPC();
  const [draft, setDraft] = useState('');
  const messagesQuery = useQuery(crpc.messages.list.queryOptions());
  const createMessage = useMutation(crpc.messages.create.mutationOptions());

  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    const body = draft.trim();
    if (!body) return;

    try {
      await createMessage.mutateAsync({ body });
      setDraft('');
    } catch {}
  }

  return (
    <main>
      <form onSubmit={handleSubmit}>
        <input
          onChange={(event) => setDraft(event.target.value)}
          value={draft}
        />
        <Button disabled={createMessage.isPending} type="submit">
          {createMessage.isPending ? 'Saving...' : 'Add message'}
        </Button>
      </form>

      {messagesQuery.isPending ? (
        <p>Loading messages...</p>
      ) : messagesQuery.isError ? (
        <div>Backend not ready. Start kitcn dev and refresh.</div>
      ) : (
        <ul>
          {messagesQuery.data.map((message) => (
            <li key={message.id}>{message.body}</li>
          ))}
        </ul>
      )}
    </main>
  );
}
```

--------------------------------

### Manual app creation with Next.js, Tailwind, and Convex

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/setup/index.md

Steps for manually creating a Next.js application and installing necessary dependencies like Convex, KitCN, Zod, and React Query.

```bash
bunx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir
cd my-app
bun add convex kitcn zod @tanstack/react-query
```

--------------------------------

### Environment Variables - Local

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/nextjs/index.mdx

Environment variables for local development setup.

```bash
# WebSocket API (port 3210)
NEXT_PUBLIC_CONVEX_URL=http://localhost:3210

# HTTP routes (port 3211)
NEXT_PUBLIC_CONVEX_SITE_URL=http://localhost:3211

# Better Auth
NEXT_PUBLIC_SITE_URL=http://localhost:3000
```

--------------------------------

### Checking Status - Get Job Status

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/features/scheduling.md

Example of querying the `_scheduled_functions` system table to get the status of a specific job using `ctx.orm.system.get()`.

```typescript
export const getJobStatus = publicQuery
  .input(z.object({ jobId: z.string() }))
  .output(z.object({
    name: z.string(),
    scheduledTime: z.number(),
    completedTime: z.number().optional(),
    state: z.object({ kind: z.enum(['pending', 'inProgress', 'success', 'failed', 'canceled']) }),
  }).nullable())
  .query(async ({ ctx, input }) => {
    return await ctx.orm.system.get(input.jobId);
  });
```

--------------------------------

### Before

Source: https://github.com/udecode/kitcn/blob/main/docs/plans/2026-01-27-docs-migration-guide-from-convex-dev-better-auth-plan.md

Example of the auth.config.ts file before migration.

```typescript
import { getAuthConfigProvider } from "@convex-dev/better-auth/auth-config";
import type { AuthConfig } from "convex/server";

export default {
  providers: [getAuthConfigProvider()],
} satisfies AuthConfig;
```

--------------------------------

### Cache Invalidation Example

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/features/http.md

Provides an example of how to invalidate cache queries after a mutation, specifically for updating and getting a single todo item.

```typescript
const updateTodo = useMutation(
  crpc.http.todos.update.mutationOptions({
    onSuccess: (_, vars) => {
      queryClient.invalidateQueries(crpc.http.todos.list.queryFilter());
      queryClient.invalidateQueries(
        crpc.http.todos.get.queryFilter({ params: { id: vars.params?.id } })
      );
    },
  })
);
```

--------------------------------

### Starter schema definition

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/quickstart.mdx

Defines a simple schema with a 'messages' table containing a 'body' field.

```typescript
import { convexTable, defineSchema, text } from 'kitcn/orm';

export const messagesTable = convexTable('messages', {
  body: text().notNull(),
});

export const tables = {
  messages: messagesTable,
};

export default defineSchema(tables);
```

--------------------------------

### Define Your Schema

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/server/setup.mdx

Define your database schema using the ORM. This example shows how to define 'user' and 'session' tables with indexes and relations.

```typescript
import {
  convexTable,
  defineSchema,
  id,
  index,
  integer,
  text,
} from 'kitcn/orm';

export const user = convexTable(
  'user',
  { name: text().notNull(), email: text().notNull() },
  (t) => [index('email').on(t.email)]
);

export const session = convexTable(
  'session',
  {
    token: text().notNull(),
    userId: id('user').notNull(),
    expiresAt: integer().notNull(),
  },
  (t) => [index('token').on(t.token), index('userId').on(t.userId)]
);

export const tables = { user, session };
export default defineSchema(tables, {
  strict: false,
}).relations((r) => ({
  user: {
    sessions: r.many.session({ from: r.user.id, to: r.session.userId }),
  },
  session: {
    user: r.one.user({ from: r.session.userId, to: r.user.id }),
  },
}));
```

--------------------------------

### Context Setup - Before (Ents)

Source: https://github.com/udecode/kitcn/blob/main/www/content/docs/migrations/ents.mdx

Example of setting up the context with Convex Ents.

```typescript
import { entsTableFactory } from 'convex-ents';
import { entDefinitions } from '../schema';

export function makeCtx(ctx: any) {
  const table = entsTableFactory(ctx, entDefinitions);
  return { ...ctx, table };
}
```

--------------------------------

### Install auth with CLI

Source: https://github.com/udecode/kitcn/blob/main/packages/kitcn/skills/kitcn/references/setup/auth.md

Commands to initialize kitcn and add the auth package.

```bash
npx kitcn@latest init -t next --yes
```

```bash
bunx kitcn add auth --yes
```

--------------------------------

### After (convex/convex.config.ts)

Source: https://github.com/udecode/kitcn/blob/main/docs/plans/2026-01-27-docs-migration-guide-from-convex-dev-better-auth-plan.md

Example of the convex.config.ts file after migration.

```typescript
import { defineApp } from "convex/server";
import resend from "@convex-dev/resend/convex.config";

const app = defineApp();
app.use(resend);  // Keep other components

export default app;
```