create-cooktype-app

CLI to scaffold AI-promptable monorepos with Next.js, Convex, and Shadcn/ui. Designed for developers and vibe-coders who need bleeding-edge features and a streamlined development experience with sensible defaults.

This project scaffold is designed specifically to work with Claude Code but may work with other AI systems as well.

Use the backend: prefix in your requests to use a Convex Chef-inspired system prompt for building your backend.

Use the frontend: prefix in your requests to use a Vercel v0-inspired system prompt for building your frontend.

Quick Start

pnpm dlx create-cooktype-app

Or with npm:

npx create-cooktype-app

You'll be prompted for a project name (default: my-cooktype-app). You can also pass it directly:

pnpm dlx create-cooktype-app my-app

What You Get

A Turborepo monorepo with:

my-app/
├── apps/
│   └── web/                 # Next.js frontend (App Router)
├── packages/
│   ├── ui/                  # Shared Shadcn/ui components (@workspace/ui)
│   └── backend/             # Convex backend (@workspace/backend)
├── .claude/
│   ├── settings.json        # MCP servers and permissions
│   └── commands/
│       ├── setup-project.md   # Local dev environment setup
│       └── deploy-project.md  # Guided deployment walkthrough
├── CLAUDE.md                # AI assistant instructions with mode switching
└── turbo.json               # Turborepo configuration

Features:

• Curated Shadcn/ui components pre-installed and extracted to a shared package
• Convex backend with local development (no account needed to start)
• ConvexProvider already wired up in the frontend
• CLAUDE.md files for AI-assisted development (backend/frontend modes)
• Claude Code skills and MCP servers pre-configured
• /setup-project command for local dev environment setup
• /deploy-project command for guided production deployment
• GitHub Actions CI workflow
• TypeScript throughout

Usage

Basic

create-cooktype-app my-app

With Options

# Skip git initialization
create-cooktype-app my-app --noGit

# Skip dependency installation
create-cooktype-app my-app --noInstall

# Skip Convex setup
create-cooktype-app my-app --noConvex-init

# Combine options
create-cooktype-app my-app --noInstall --noConvex-init

Interactive Theme Selection

When you run the CLI, you'll be prompted to configure your Shadcn theme:

? Use default Shadcn theme? (Vega style, Zinc colors, Phosphor icons) (Y/n)

Press Y to use defaults, or N to customize:

• Style: Vega, Nova, Maia, Lyra, Mira
• Base Color: Neutral, Stone, Zinc, Gray
• Theme Color: Base color or Amber, Blue, Cyan, Emerald, Fuchsia, Green, Indigo, Lime, Orange, Pink, Purple, Red, Rose, Sky, Teal, Violet, Yellow
• Icon Library: Lucide, Tabler, HugeIcons, Phosphor, Remix
• Menu Color: Default, Inverted

After Scaffolding

The scaffold sets up a local Convex deployment, so you can start developing immediately without creating any accounts.

cd my-app
pnpm dev

This starts both the Convex backend (locally) and the Next.js frontend. Environment variables are configured automatically during scaffold.

Cloned the repo or skipped Convex init? Open Claude Code and run /setup-project — it will install dependencies, initialize a local Convex backend, and configure the environment variables for you.

When you're ready to deploy to production, run /deploy-project for a guided walkthrough covering GitHub, Convex cloud, and Vercel.

Project Structure

apps/web

Next.js frontend with App Router.

// Import UI components from the shared package
import { Button } from "@workspace/ui/components/button";
import { Card } from "@workspace/ui/components/card";

// Import Convex hooks and API
import { useQuery, useMutation } from "convex/react";
import { api } from "@workspace/backend/convex/_generated/api";

export function MyComponent() {
  const users = useQuery(api.functions.users.list);
  const createUser = useMutation(api.functions.users.create);
  // ...
}

packages/ui

Shared Shadcn/ui component library. All components are pre-installed.

# Add more components
cd packages/ui
pnpm dlx shadcn@latest add <component-name>

packages/backend

Convex backend with real-time database and serverless functions.

convex/
├── _generated/      # Auto-generated types (don't edit)
├── functions/       # Your queries, mutations, actions
└── schema.ts        # Database schema

Claude Code Integration

The scaffolded project comes pre-configured for Claude Code with MCP servers, skills, and custom commands.

MCP Servers

Convex MCP is pre-configured in .claude/settings.json and available immediately. It lets Claude Code interact with your Convex backend — query data, inspect tables, run functions, and manage environment variables.

GitHub MCP and Vercel MCP can be added when you're ready to deploy. The /deploy-project command walks you through setting them up.

Skills

Four Claude Code skills are installed during scaffolding:

| Skill | Purpose | |-------|---------| | vercel-react-best-practices | React/Next.js performance patterns from Vercel Engineering | | web-design-guidelines | Web interface design and accessibility audit | | agent-browser | Browser automation for testing and interaction | | copywriting | Marketing copy, landing pages, and CTAs |

/setup-project Command

Run /setup-project in Claude Code to set up the local development environment. It handles:

1. Installing dependencies
2. Initializing a local Convex backend (no account needed)
3. Configuring NEXT_PUBLIC_CONVEX_URL in apps/web/.env.local

Use this after cloning the repo, or if you scaffolded with --noConvex-init.

/deploy-project Command

When you're ready to go to production, run /deploy-project in Claude Code. It guides you through:

1. Creating a GitHub repository
2. Deploying Convex to the cloud
3. Deploying the web app to Vercel
4. Setting up CI/CD with GitHub Actions

CLAUDE.md Mode Switching

The generated CLAUDE.md files enable AI assistants to switch between specialized modes:

Backend Mode (prefix with backend:):

• Focus on Convex schema, queries, mutations, actions
• Work in packages/backend/convex/
• Use proper validators, indexes, and Convex patterns

Frontend Mode (prefix with frontend:):

• Focus on layout, design, animation, polish
• Work in apps/web/
• Follow design system guidelines

Example prompts:

backend: Add a posts table with author reference and create CRUD functions

frontend: Create a dashboard page with a sidebar and user list

Commands

From the project root:

pnpm dev          # Start all apps in development
pnpm build        # Build all packages
pnpm lint         # Lint all packages
pnpm typecheck    # Type check all packages

Requirements

• Node.js 20+
• pnpm (recommended) or npm

Releasing New Versions (Maintainers)

1. Update version in package.json
2. Commit and push:

   git add -A
   git commit -m "Bump version to X.Y.Z"
   git push

3. Create and push a tag:

   git tag vX.Y.Z
   git push origin vX.Y.Z

4. Publish to npm:

   pnpm build
   npm publish

How It Works

flowchart TD
    Start([pnpm dlx create-cooktype-app]) --> Prompt[Prompt for project name & theme]
    Prompt --> Validate[Validate project directory]
    Validate --> Shadcn[Run shadcn create with selected theme]
    Shadcn --> Components[Install curated Shadcn components]
    Components --> Monorepo[Transform into Turborepo monorepo]

    Monorepo --> Convex[Add Convex backend package]
    Convex --> Provider[Wire up ConvexProvider in Next.js]
    Provider --> Turbo[Add Turborepo configuration]

    Turbo --> Claude[Add CLAUDE.md files & .claude/ settings]
    Claude --> CI[Add GitHub Actions CI workflow]

    CI --> Git{--noGit?}
    Git -- No --> InitGit[Initialize git repository]
    Git -- Yes --> Install

    InitGit --> Install{--noInstall?}
    Install -- No --> Deps[Install dependencies]
    Install -- Yes --> Done

    Deps --> Skills[Install Claude Code skills]
    Skills --> ConvexInit{--noConvex-init?}
    ConvexInit -- No --> Local[Initialize Convex locally]
    ConvexInit -- Yes --> Done

    Local --> Done([Ready — run pnpm dev])

Acknowledgments

The AI-assisted development guidelines (CLAUDE.md files) are inspired by:

• Convex Chef — Convex's AI assistant for building real-time backends. The backend mode guidelines are adapted from Chef's system prompts.
• Vercel v0 — Vercel's generative UI tool. The frontend mode design system and component patterns are inspired by v0's approach to building polished interfaces.

License

MIT — see LICENSE for details.