Installation

Install Gencow and create your first project

Prerequisites

Bun (recommended) — the simplest all-in-one runtime, package manager, and bunx CLI runner for Gencow

Bun alone is enough to use the Gencow CLI and local runtime. Node.js with npm/npx, and pnpm, are also supported. These docs use bun and bunx as the recommended default.

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
bunx gencow@latest init my-app
cd my-app

# Or initialize in current directory
bunx gencow@latest init . --force

If your project already uses Node.js, the equivalent npx commands also work:

npx gencow@latest init my-app
npx gencow@latest init . --force

Choosing Which CLI Version Runs

bunx gencow@latest is the documentation default. npx gencow@latest is a fully supported alternative for Node.js users. In both forms, @latest asks the package registry for the version currently published under the latest tag. The runner reuses the matching package from its cache when possible, so it does not download the same files on every invocation.

Registry metadata is also cached, so a newly published version can take a short time to become visible immediately after release. See the official Bun `bunx` documentation and npm `npx` documentation.

Running plain gencow can select a project-installed, version-pinned CLI (or another gencow binary already on your PATH). Use plain gencow when that is intentional; use bunx gencow@latest when you want the current published CLI.

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
│   ├── schema-auth.ts     ← User-owned auth tables
│   ├── generated/         ← Server codegen (created by `gencow init` / `gencow codegen`)
│   │   ├── schema-auth.gen.ts ← Generated auth schema metadata
│   │   └── db-schema.gen.ts   ← Aggregated schema for typed ctx.db
│   ├── auth.ts            ← Auth configuration
│   ├── runtime.ts         ← Typed `procedure`, `httpRoute`, and `createCrud` bound to your schema + auth
│   ├── index.ts           ← Registers API via `defineApi`
│   ├── SECURITY.md        ← Security checklist for AI coders
│   ├── .env               ← Backend secrets/runtime vars (local only)
│   └── (template files)   ← Depends on chosen template
├── gencow.config.js       ← Project configuration
├── drizzle.config.ts      ← Database config
├── tsconfig.json
├── package.json
├── .env                   ← Frontend build-time variables (local only)
└── .gitignore

Auto-Installed Dependencies

Package	Purpose
`gencow`	CLI + bundled server runtime
`@gencow/core`	`defineApi`, `ownerRls`, `cron`, `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 `src/gencow/api.ts`, `createAuthClient`, `createGencowClient` (`apiClient`)
`@gencow/react`	`GencowProvider`, `useQuery`, `useMutation`, `useAuth`

bun add @gencow/client @gencow/react

Typical setup: createGencowClient({ api, baseUrl, auth }) → apiClient → <GencowProvider apiClient={apiClient}>. See Client SDK and React Hooks.

For TanStack Query (experimental), also install @gencow/tanstack-query and @tanstack/react-query. Start with the TanStack Query guide for setup, then use the API reference for the exported surface.

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)
bunx gencow@latest init my-app

# Or specify directly
bunx gencow@latest 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	`admin-tool`	Internal admin tool (no auth)	items.ts with anonymous CRUD; no `auth.ts`
4	`fullstack`	Tasks + Files + AI Chat + Agent	All of task-app + ai.ts + prompt.md
5	`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
bunx gencow@latest templates list

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

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

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

bun run build
bunx 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

Default development runs on Gencow Cloud, so log in first:

bunx gencow@latest login
bunx gencow@latest dev

This watches backend files, deploys changes to the cloud dev app, streams logs, and regenerates gencow/generated/*, src/gencow/api.ts, and the generated developer guide.

For a fully local Bun + PGlite runtime instead:

bunx gencow@latest dev --local

Local mode starts the API at http://localhost:5456 and the Admin Dashboard at http://localhost:5456/_admin. See Local Development for the database, storage, env, reset, and restore commands.

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
bunx gencow@latest init . --force

# Install dependencies
bun install

# Start Gencow backend
bunx gencow@latest dev --local

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

Quickstart — Build a Todo app in 5 minutes
Project Structure — Understand every file
Schema Guide — Learn about schema patterns

Introduction Quickstart