DOCSEARCHbyAlgolia
Submit Docs

kitcn Documentation

repository·main·Indexed 19 days ago

https://github.com/udecode/kitcn

A type-safe framework built on top of Convex featuring cRPC (a tRPC-style server API), a Drizzle-style ORM, and seamless TanStack Query integration for React applications. kitcn provides a cohesive developer experience with dedicated packages for Next.js RSC support, Better Auth integration, rate limiting, and a CLI for project initialization and codegen.

Tokens
411.4K
Snippets
1.2K
Records
1.6K
Agent score
62%

What's inside kitcn

  1. Overview of Better-Convex ORM Documentation Structure

    main

    The Better-Convex ORM documentation is designed to help developers (especially those migrating from Drizzle or Prisma) understand how to use the ORM within the Convex ecosystem. The documentation follows a progressive disclosure model using a three-column layout: Quick Start | Core Docs | Advanced/Reference.

    Key documentation areas include:

    • Schema: Defining convexTable(), relations (one(), many()), indexes, and type inference/validators.
    • Queries: Using findMany(), findFirst(), column selection, filtering, ordering, pagination (limit/offset + cursor), and joins via the with option.
    • Mutations: Performing insert().values(), update().set().where(), and delete().where() operations.
    • Advanced Topics: Type-safety patterns, dynamic query building, and Convex reactivity (real-time features).
    • Migration Guides: Specific paths for migrating from Drizzle, Prisma, or Ents to Better-Convex.
    • Reference: Complete API surface, filter operators, and feature limitations.

  2. Introduction to kitcn

    main

    kitcn is a complete framework designed for building type-safe, real-time applications using Convex. It unifies several core technologies into a single developer experience:

    • Convex: For real-time data and backend logic.
    • TanStack Query: For client-side caching and state management.
    • Better Auth: For authentication.
    • cRPC: A tRPC-style API pattern for end-to-end type safety.
    • Drizzle-style ORM: For schema definition and query helpers.

    Key features include end-to-end type safety from schema to client, real-time WebSocket subscriptions that flow directly into the TanStack Query cache, and a design that allows for incremental adoption of its features.

  3. Overview of kitcn features and packages

    main

    kitcn is a type-safe Convex framework that provides a cohesive developer experience across the stack. Key features include:

    • Server API: A tRPC-style procedure builder via kitcn/server (referred to as cRPC).
    • ORM: A Drizzle-style ORM designed for Convex via kitcn/orm.
    • Client Integration: React and TanStack Query integration with support for real-time updates via kitcn/react.
    • Next.js Support: Server helpers for React Server Components (RSC) and authentication via kitcn/auth/nextjs and kitcn/rsc.
    • Authentication: Utilities for Better Auth including kitcn/auth, kitcn/auth/client, kitcn/auth/config, and kitcn/auth/http.
    • Rate Limiting: A plugin for managing request rates via kitcn/ratelimit.
    • CLI Tooling: A kitcn binary providing codegen, registry management, and runtime analysis.

  4. Overview of GitHub Slash Commands for Claude Code Action

    main

    The Claude Code Action supports stepwise PR and issue workflows via GitHub comments using specific slash commands. These commands are defined as .claude/commands/*.md files and allow an AI agent to perform structured tasks like requirement exploration, planning, implementation, and review.

    Command Summary

    CommandPurposeAuto-commitAllowed Tools
    /brainstormExplore requirements via Q&ANoRead, Grep, Glob, WebFetch
    /planCreate implementation planNoRead, Grep, Glob, Write (docs/)
    /workImplement changesYesAll standard + Bash(bun:), Bash(gh:)
    /reviewReview code, update PRYesRead, Bash(gh pr:*)

  6. Overview of the kitcn ORM

    main

    The kitcn ORM provides a Drizzle-style relational query builder designed specifically for Convex's document model. It brings type-safe relational querying and mutations to Convex while maintaining compatibility with Convex's underlying storage.

    Key Features:

    • Schema & Relations: Uses convexTable, .relations(...), one, and many to define data structures.
    • Type-safe Queries: Supports findMany, findFirst, cursor pagination, where, orderBy, and with for relation loading.
    • Mutations: Provides insert, update, delete, returning, and onConflictDoUpdate.
    • Security: Supports runtime Row Level Security (RLS) via rlsPolicy and convexTable.withRLS.
    • Type Inference: Full end-to-end TypeScript inference using InferSelectModel and $inferSelect.

    Note: ctx.orm is attached to the context during setup. All queries and mutations are accessed via ctx.orm.

  7. Compare kitcn vs. Vanilla Convex

    main

    kitcn is an extension for Convex, not a replacement. It builds on top of Convex's real-time database by adding a tRPC-style API surface and deep TanStack Query integration.

    Key differences include:

    • Server: Adds a fluent builder, middleware, and Zod validation to standard query, mutation, and action functions.
    • Client: Replaces/extends useQuery and useMutation with TanStack Query features like isPending, refetch(), and auth-aware skipping.
    • SSR: Extends preloadQuery() with prefetch(), a caller for direct server calls, and HydrateClient for automatic hydration.
    • Errors: Maps ConvexError to CRPCError with associated HTTP status codes.

  8. Understand the kitcn project structure

    main

    The kitcn application is built using Next.js and Fumadocs. Key files and routes include:

    • lib/source.ts: Contains the code for the content source adapter. Use the loader() interface provided here to access your content.
    • lib/layout.shared.tsx: Contains shared options for layouts. It is optional but recommended to keep this for consistency.
    • app/(home): The route group containing the landing page and other primary pages.
    • app/docs: The directory for documentation layouts and pages.
    • app/api/search/route.ts: The Route Handler responsible for search functionality.

  9. Planned Drizzle-Convex Success Criteria

    main

    The development of Drizzle-Convex is tracked through four distinct phases of capability:

    1. Phase 1 (Schema + Relations): Ability to define tables and relations with TypeScript, achieving full type inference via InferSelectModel and InferInsertModel while generating valid Convex schemas.
    2. Phase 2 (Queries): Implementation of findMany() and findFirst() with relations, ensuring type-safe results and proper nullability tracking.
    3. Phase 3 (Mutations): Support for type-validated inserts, updates with where clauses, deletions, and relation mutations (adding/removing edges).
    4. Phase 4 (Polish): Achieving documentation parity, providing migration guides from convex-ents, and establishing performance benchmarks.

  10. Understand the kitcn CLI command structure

    main

    The kitcn CLI is organized into two primary functional areas: Registry and Backend.

    Registry Commands

    Used for project setup and feature management:

    • init: Initialize a project.
    • create: Create a starter.
    • add: Add features (like auth or plugins).
    • view: Preview plans.
    • info: Inspect registry details.
    • docs: View documentation.

    Backend Commands

    Used for backend workflows and data lifecycle management:

    • dev: Run the development environment.
    • codegen: Generate code.
    • env: Manage environment variables.
    • deploy: Deploy the backend.
    • aggregate *: Aggregate data.
    • migrate *: Run migrations.
    • reset: Reset the backend.
    • analyze: Run diagnostics/analyze bundles.

  11. Planned Query Support Features in kitcn

    main

    The upcoming M6.5 milestone for kitcn focuses on completing the query runtime to ensure that type-safe relation loading works at runtime, not just in TypeScript types.

    Key features being implemented include:

    • Relation loading runtime: Enabling the with: { relationName: true } syntax to actually fetch and populate related data.
    • Nested relations: Supporting deep relation trees, e.g., with: { posts: { with: { comments: true } } }.
    • Relation filters/limits: Allowing fine-grained control over related data via where, limit, and orderBy within the with object.
    • Cursor pagination: Implementing Convex-native .paginate({ cursor, numItems }) to leverage $O(1)$ performance instead of $O(n)$ offset-based pagination.

  12. Classify candidates during vision sync

    main

    During the vision sync process, every identified candidate must be classified to determine how it affects the project's doctrine. Candidates should be categorized into one of the following classes:

    • doctrine: Reusable high-level principles.
    • plan/map: Structural or strategic documentation.
    • ADR/analysis: Architecture Decision Records or analytical documents.
    • workflow: Process and operational documentation.
    • implementation detail: Low-level technical specifics (which vision should not own).
    • rejected/superseded: Items that are no longer relevant.
    • contradiction: Conflicts that require resolution.