Keel

The full-stack framework built for AI.
Ship production apps faster. Every project ships with typed contracts, predictable patterns, and AI agent instructions — so AI writes better code from the start.

Website · Docs · npm

_{a project}

Keel is a full-stack template framework for building web + mobile apps. It gives you auth, database, email, and native mobile support out of the box — and it's designed so that AI coding agents (Cursor, Copilot, Windsurf, etc.) produce better code when working in Keel projects.

Every generated project includes CLAUDE.md, .cursor/rules, .github/copilot-instructions.md, and more — giving AI agents full context about your architecture, conventions, and patterns.

# Create a new project
npx @codaijs/keel create my-app

# Follow the setup wizard — it configures everything:
#   → Project name & branding
#   → Database connection
#   → Auth secrets
#   → Email provider (optional)
#   → Which sails to install

npx @codaijs/keel create my-app --yes --db=pglite
cd my-app
keel dev

Uses PGlite (embedded PostgreSQL via WASM) — full PostgreSQL compatibility without Docker.

git clone https://github.com/Chafficui/keel.git my-app
cd my-app
npm install

# Start PostgreSQL
docker compose up -d

# Copy environment files
cp packages/backend/.env.example packages/backend/.env
# Edit .env with your database URL, secrets, etc.

# Run database migrations
npm run db:migrate

# Start development
npm run dev

packages/
  shared/      → @keel/shared    — Types + Zod validators
  email/       → @keel/email     — React Email templates
  frontend/    → @keel/frontend  — Vite + React SPA + Capacitor
  backend/     → @keel/backend   — Express 5 API server
sails/         → Tracks installed sails (minimal, no code shipped)
cli/           → create-keel CLI + sail definitions
docs/          → Architecture, auth flow, mobile, sail development guides
brand/         → Keel brand assets + design guide

npm run dev               # Frontend (:5173) + Backend (:3005) concurrently
npm run dev:frontend      # Frontend only
npm run dev:backend       # Backend only
npm run dev:email         # Email template preview (:3010)

npm run db:generate       # Generate migration from schema changes
npm run db:migrate        # Apply pending migrations
npm run db:push           # Push schema directly (dev only)
npm run db:studio         # Open Drizzle Studio GUI

npm run cap:sync          # Sync web build to native projects
npm run cap:ios           # Open iOS project
npm run cap:android       # Open Android project

npm run build             # Build all packages
npm run typecheck         # Type-check everything
keel deploy               # Show deployment guides

Sails are optional packages that add functionality to your Keel project. They're not bundled into your app — install only what you need.

# List available sails
npx @codaijs/keel list

# Install a sail (runs interactive setup wizard)
npx @codaijs/keel sail add google-oauth

# Get info about a sail before installing
npx @codaijs/keel info stripe

Every sail includes a setup wizard that walks you through configuration, prompts for required env vars, and handles file modifications automatically.

Sails use marker comments in your codebase to know where to insert code:

// [SAIL_IMPORTS]           — import statements
// [SAIL_ROUTES]            — route registrations
// [SAIL_SCHEMA]            — database schema exports
// [SAIL_SOCIAL_PROVIDERS]  — OAuth provider config
// [SAIL_ENV_VARS]          — environment variable declarations
{/* [SAIL_SOCIAL_BUTTONS] */} — social login buttons in forms

If you've modified files and a marker is missing, the installer won't break your code — it prints clear manual instructions instead.

Every project generated by Keel includes instruction files for major AI coding tools:

These files give AI agents full context about your project's architecture, conventions, database schema, auth flow, and available commands — resulting in more accurate code generation and fewer hallucinations.

Detailed guides in the docs/ folder:

• Architecture Overview — system design, data flow, deployment
• Auth Flow — registration, login, sessions, token handling
• Capacitor Guide — mobile setup, deep links, native features
• GDPR Compliance — consent, export, deletion (used by gdpr sail)
• Sail Development — how to build your own sails

• Node.js ≥ 22
• PostgreSQL 16+ (or use the included docker-compose.yml)
• npm 10+

MIT

_{Built with}