create-agentic-stack

AI-optimized full-stack scaffolding for Cloudflare

A CLI tool that scaffolds production-ready TypeScript applications optimized for AI-assisted development. The key insight: no generators, no plugins - AI generates all your application code by reading structured "Skills" documentation.

Why Agentic Stack?

Traditional scaffolding tools have generators (generate component, generate crud). These are:

• Rigid - flag-based, template-bound
• High maintenance - templates need constant updates
• Redundant - AI can generate better, context-aware code

Agentic Stack eliminates generators entirely. Instead:

• CLI scaffolds infrastructure only (monorepo, configs, packages)
• AI generates all application code via Skills (structured documentation)
• You describe what you want in natural language, AI builds it

Quick Start

# Create a new project
pnpm create agentic-stack my-app

# Or with npm/npx
npx create-agentic-stack my-app

Follow the interactive prompts to configure your project, then:

cd my-app
cp .env.example .env  # Add your database URL
pnpm install
pnpm dev

To add features, ask your AI assistant:

• "Create a CRUD for products with name, price, description"
• "Add Better Auth with Google and GitHub login"
• "Create a dashboard page with charts"

Your AI reads the Skills in .claude/skills/ and generates the right code for your stack.

Tech Stack

Frontend

| Technology | Version | Purpose | |------------|---------|---------| | TanStack Start | 1.95.x | Meta-framework (SSR + routing) | | React | 19.x | UI framework | | TanStack Query | 5.x | Server state management | | Zustand | 5.x | Client state management | | TailwindCSS | 4.x | Styling | | shadcn/ui | Latest | Component library |

Backend

| Technology | Version | Purpose | |------------|---------|---------| | Hono | 4.x | Web framework | | @hono/zod-openapi | 0.18.x | OpenAPI + validation | | Zod | 3.24.x | Schema validation | | Drizzle ORM | 0.38.x | Database ORM |

Database Options

| Option | Best For | |--------|----------| | Neon PostgreSQL (default) | Production apps, complex queries | | Cloudflare D1 | Internal tools, SQLite simplicity |

Infrastructure

| Service | Purpose | |---------|---------| | Cloudflare Pages | Frontend hosting (app.domain.com) | | Cloudflare Workers | API hosting (api.domain.com) |

Dev Tools

| Tool | Version | Purpose | |------|---------|---------| | TypeScript | 5.6.x | Type safety | | Biome | 1.9.x | Linting + formatting | | Vitest | 2.x | Unit testing | | pnpm | 9.x | Package manager |

CLI Usage

Interactive Mode

pnpm create agentic-stack my-app

You'll be prompted for:

• Project name - Your app's name
• Database - Neon PostgreSQL or Cloudflare D1
• Domain - For cookie sharing (e.g., myapp.com)
• Runtime - Node.js or Bun
• Git - Initialize git repository
• Install - Install dependencies

Non-Interactive Mode

pnpm create agentic-stack my-app \
  --db neon \
  --domain myapp.com \
  --runtime node \
  --git \
  --install \
  -y

CLI Flags

| Flag | Values | Default | Description | |------|--------|---------|-------------| | --db | neon, d1 | neon | Database type | | --domain | string | - | Domain for cookie sharing (required with -y) | | --runtime | node, bun | node | Runtime environment | | --git | boolean | true | Initialize git repository | | --no-git | - | - | Skip git initialization | | --install | boolean | true | Install dependencies | | --no-install | - | - | Skip dependency installation | | -y, --yes | - | - | Use defaults, skip prompts |

Generated Project Structure

my-app/
├── .claude/
│   └── skills/                 # AI documentation (Skills)
│       ├── STACK.md            # Stack overview, conventions
│       ├── CONTRACTS.md        # Zod schema rules
│       ├── DATABASE.md         # Drizzle schemas, repositories
│       ├── API.md              # Hono routes, middleware
│       ├── FRONTEND.md         # Pages, components, hooks
│       ├── CRUD.md             # Full CRUD creation guide
│       ├── AUTH.md             # Better Auth setup
│       ├── ERRORS.md           # Error handling patterns
│       └── TESTING.md          # Unit + E2E testing
│
├── .cursor/
│   └── rules                   # Auto-generated Cursor rules
│
├── .github/
│   └── workflows/
│       ├── ci.yml              # Lint, typecheck, test
│       └── deploy.yml          # Deploy to Cloudflare
│
├── apps/
│   ├── api/                    # Backend (Hono)
│   │   ├── src/
│   │   │   ├── routes/         # API routes
│   │   │   ├── middleware/     # CORS, auth, rate limiting
│   │   │   ├── lib/            # Utilities
│   │   │   └── index.ts        # Entry point
│   │   ├── wrangler.toml       # Cloudflare Worker config
│   │   └── package.json
│   │
│   └── web/                    # Frontend (TanStack Start)
│       ├── src/
│       │   ├── routes/         # File-based routing
│       │   ├── components/     # React components
│       │   ├── hooks/          # Custom hooks
│       │   ├── stores/         # Zustand stores
│       │   └── styles/         # CSS
│       ├── app.config.ts       # TanStack Start config
│       └── package.json
│
├── packages/
│   ├── contracts/              # Zod schemas (shared types)
│   │   └── src/
│   │       ├── common/
│   │       │   ├── errors.ts   # ApiError schema
│   │       │   └── pagination.ts
│   │       └── index.ts
│   │
│   ├── config/                 # Environment validation
│   │   └── src/
│   │       ├── env.ts          # Zod env validation
│   │       └── constants.ts
│   │
│   ├── db/                     # Database layer
│   │   └── src/
│   │       ├── schema/         # Drizzle schemas
│   │       ├── repositories/   # Data access
│   │       └── client.ts       # DB connection
│   │
│   └── api-client/             # Generated typed client
│       └── src/
│           ├── client.ts       # Fetch wrapper
│           ├── errors.ts       # ApiError class
│           ├── hooks/          # TanStack Query hooks
│           └── types.ts        # Generated from OpenAPI
│
├── scripts/
│   ├── generate-cursor-rules.ts
│   └── generate-api-client.ts
│
├── .env.example
├── biome.json
├── package.json
├── pnpm-workspace.yaml
└── tsconfig.json

Package Dependencies

@repo/contracts ◄─── LEAF NODE (only depends on zod)
       │
       ▼
@repo/config
       │
       ▼
@repo/db
       │
       ▼
@repo/api-client ◄─── GENERATED (do not edit manually)
       │
       ▼
apps/api ←──────────────────────────┐
                                    │
apps/web ───────────────────────────┘

Available Commands

After creating your project, these commands are available:

Development

| Command | Description | |---------|-------------| | pnpm dev | Start API (port 8787) and web (port 3000) | | pnpm dev:api | Start API only | | pnpm dev:web | Start web only |

Build & Deploy

| Command | Description | |---------|-------------| | pnpm build | Build all packages | | pnpm deploy | Deploy to Cloudflare | | pnpm deploy:api | Deploy API to Workers | | pnpm deploy:web | Deploy web to Pages |

Database

| Command | Description | |---------|-------------| | pnpm db:push | Push schema to database | | pnpm db:migrate | Generate and run migrations | | pnpm db:studio | Open Drizzle Studio | | pnpm db:seed | Run seed script |

Code Quality

| Command | Description | |---------|-------------| | pnpm lint | Lint with Biome | | pnpm lint:fix | Fix lint issues | | pnpm typecheck | TypeScript type checking | | pnpm test | Run tests |

API Client Generation

| Command | Description | |---------|-------------| | pnpm api:spec | Generate OpenAPI spec | | pnpm api:generate | Generate typed client from spec | | pnpm skills:sync | Regenerate Cursor rules from Skills |

Skills System

Skills are structured documentation files that AI assistants read to generate code correctly for your stack.

Available Skills

| Skill | Purpose | |-------|---------| | STACK.md | Stack overview, conventions, file locations | | CONTRACTS.md | Zod schema creation rules | | DATABASE.md | Drizzle schemas, repositories | | API.md | Hono routes, OpenAPI, middleware | | FRONTEND.md | TanStack Start pages, components | | CRUD.md | Step-by-step CRUD creation guide | | AUTH.md | Better Auth integration | | ERRORS.md | Error handling patterns | | TESTING.md | Vitest unit tests, Playwright E2E |

How Skills Work

1. You ask AI: "Create a CRUD for products"
2. AI reads .claude/skills/CRUD.md
3. AI follows step-by-step instructions
4. AI generates code matching project conventions
5. You review and commit

Cursor Integration

Skills are automatically synced to .cursor/rules for Cursor IDE. Run pnpm skills:sync after editing any skill file.

Deployment Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         CLOUDFLARE                              │
│                                                                 │
│  ┌─────────────────────────┐    ┌─────────────────────────────┐│
│  │    app.myapp.com        │    │      api.myapp.com          ││
│  │    Cloudflare Pages     │    │      Cloudflare Worker      ││
│  │                         │    │                             ││
│  │  ┌───────────────────┐  │    │  ┌───────────────────────┐  ││
│  │  │  TanStack Start   │  │    │  │  Hono Framework       │  ││
│  │  │  + React 19       │  │    │  │  + Zod OpenAPI        │  ││
│  │  └───────────────────┘  │    │  └───────────────────────┘  ││
│  │           │              │    │              │              ││
│  │           ▼              │    │              ▼              ││
│  │  @repo/api-client ──────┼────┼──►  @repo/db              ││
│  │                         │    │              │              ││
│  └─────────────────────────┘    └──────────────┼──────────────┘│
│                                                │               │
│  Cookie: Domain=.myapp.com (shared auth)       │               │
└────────────────────────────────────────────────┼───────────────┘
                                                 │
                                                 ▼
                                    ┌─────────────────────────┐
                                    │   Neon PostgreSQL       │
                                    │   (or Cloudflare D1)    │
                                    └─────────────────────────┘

Environment Variables

# .env.example

# Database (Neon)
DATABASE_URL=postgresql://user:[email protected]/mydb?sslmode=require

# URLs (Development)
API_URL=http://localhost:8787
APP_URL=http://localhost:3000

# Frontend (VITE_ prefix for client-side)
VITE_API_URL=http://localhost:8787

# Cloudflare (for deployment)
CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_API_TOKEN=

Example Workflow

Creating a New Feature

1. Ask AI to create a CRUD:

   "Create a CRUD for products with name (string), price (number),
   description (optional string), and isActive (boolean)"

2. AI generates:

   • Zod schemas in packages/contracts/src/products.ts
   • Drizzle schema in packages/db/src/schema/products.ts
   • Repository in packages/db/src/repositories/products.ts
   • API routes in apps/api/src/routes/products/index.ts
   • Query hooks in packages/api-client/src/hooks/products.ts
   • Frontend pages in apps/web/src/routes/products/

3. Push to database and regenerate client:

   pnpm db:push
   pnpm api:generate

4. Start development:

   pnpm dev

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

License

MIT

Built with the philosophy that AI should write your application code, not templates.