Installation

Install Gencow and create your first project

Prerequisites

  • Bun (recommended) or Node.js 18+
  • npm, pnpm, or bun package manager

Frontend Stack Recommendation

For new Gencow apps, use Vite + React as the default frontend stack. It matches Gencow's static deployment flow, uses import.meta.env.VITE_API_URL, and keeps vibe-coding output simple.

Use Next.js only when the user explicitly asks for Next.js/SSR or when adding Gencow to an existing Next.js codebase.

Create a New Project

# Create in a new directory
npx gencow init my-app
cd my-app

# Or initialize in current directory
npx gencow init . --force

Flags

Flag Description
--template <name> or -t Select a template (see below)
--force or -f Initialize in a non-empty directory. Existing non-Gencow files are preserved, package.json is merged, and Gencow scaffold files may be overwritten

What Gets Created

gencow init scaffolds the project, installs dependencies, and runs codegen so server artifacts (including auth tables) land under gencow/generated/:

my-app/
├── gencow/
│   ├── schema.ts          ← Your database tables
│   ├── generated/         ← Server codegen (created by `gencow init` / `gencow codegen`)
│   │   ├── auth-schema.ts   ← Auth tables (from gencow/auth.ts)
│   │   └── db-schema.gen.ts ← Aggregated schema for typed ctx.db
│   ├── auth.ts            ← Auth configuration
│   ├── runtime.ts         ← Typed `procedure` + `createCrud` bound to your schema + auth
│   ├── crons.ts           ← Cron job scheduler (template)
│   ├── index.ts           ← Module re-exports
│   ├── SECURITY.md        ← Security checklist for AI coders
│   └── (template files)   ← Depends on chosen template
├── gencow.config.js       ← Project configuration
├── drizzle.config.ts      ← Database config
├── tsconfig.json
├── package.json
├── .env                   ← Environment variables (local only)
└── .gitignore

Auto-Installed Dependencies

Package Purpose
gencow CLI + bundled server runtime
@gencow/core defineApi, ownerRls, cronJobs, v validator; app APIs use procedure / createCrud / httpRoute from gencow/runtime.ts
drizzle-orm Type-safe SQL ORM
drizzle-kit Schema migration tool
better-auth Authentication framework
postgres PostgreSQL client

Frontend SDK (Vite + React apps)

Add these when building the recommended Vite + React UI (templates and prompt.md assume both):

Package Purpose
@gencow/client Generated api.ts defs (defineProcedureQuery, …), auth store, realtime
@gencow/react GencowProvider, useQuery, useMutation, createAuthClient + useAuth 
npm install @gencow/client @gencow/react

Version lock: Keep @gencow/client and @gencow/react on the same version (published together).

Available Templates

These are built-in starter templates created by gencow init.

# Interactive selection (default)
npx gencow init my-app

# Or specify directly
npx gencow init my-app --template fullstack
# Template Description Includes
1 default Empty project Basic schema + index.ts
2 task-app Task + Files CRUD backend tasks.ts, files.ts with full CRUD
3 fullstack Tasks + Files + AI Chat + Agent All of task-app + ai.ts + prompt.md
4 ai-chat AI Chatbot + Memory backend chat.ts, ai.ts + prompt.md

What prompt.md Contains

Templates fullstack and ai-chat include a prompt.md file — a vibe-coding prompt designed to be given to AI assistants (Cursor, Copilot, etc.). It includes:

  • All available API endpoints with types
  • Authentication setup instructions
  • useQuery / useMutation usage patterns
  • Security rules for backend code
  • Recommended UI structure

Marketplace Templates

Marketplace templates are full projects published by other Gencow users. Clone them instead of running gencow init again.

# Browse templates
npx gencow@latest templates list

# Clone a template into a new local project
npx gencow@latest templates clone <template-slug> my-app
cd my-app

# Install, log in, and deploy the cloned project
bun install
npx gencow@latest login
npx gencow@latest deploy

If the template includes a built frontend, build it and deploy backend + static files together:

bun run build
npx gencow@latest deploy --static dist/

Do not run gencow init . --force inside a cloned template. Clone downloads the project source, including its gencow/ backend and config files; init --force is for adding a fresh Gencow scaffold to an existing non-Gencow project.

Start Development

gencow dev

This starts:

  • 🔧 Hono server at http://localhost:5456 with hot-reload
  • 📊 Admin Dashboard at http://localhost:5456/_admin for data browsing
  • 🗄️ Cloud PostgreSQL — your dev database matches production
  • 📝 Auto-codegen — gencow/generated/*, src/gencow/api.ts, and related client types regenerate on file changes

Using with Existing Projects

If you already have a Vite + React project, or an existing Next.js/other frontend project:

# Navigate to your existing frontend project root
cd my-existing-project

# Initialize Gencow in the current directory
npx gencow init . --force

# Install dependencies
bun install   # or npm install

# Start Gencow backend
gencow dev

The --force flag:

  • Preserves all existing files
  • Merges Gencow dependencies into your existing package.json
  • Creates gencow/ folder alongside your existing src/
  • Skips .env and tsconfig.json if they already exist

It can overwrite Gencow-owned scaffold files such as gencow/ template files, gencow.config.js, and drizzle.config.ts. Use it only when you want to add or refresh Gencow in an existing project, not when deploying a marketplace template.

Next Steps

IntroductionQuickstart