create-vibe-code-app

🚀 A CLI tool to quickly create Next.js projects optimized for AI-driven development

create-vibe-code-app creates modern Next.js projects with TypeScript, Tailwind CSS, and AI-assistant configuration out of the box. Each project comes with a project-plan.md file and .cursor/rules/ configuration to seamlessly integrate with AI coding assistants like Cursor.

Features

• ⚡ Next.js 14 with TypeScript and modern React patterns
• 🎨 Tailwind CSS for rapid UI development
• 🤖 AI-Optimized with Cursor configuration and project plans
• 🎯 Multiple Templates - Choose from next or vercel-ai templates
• 🔧 Vercel AI SDK - Pre-configured AI chat interface (vercel-ai template)
• 📋 Project Planning with structured markdown task lists
• 🛠️ Developer Tools - ESLint, Prettier, and more
• 🌐 Remote Project Plans - Fetch project plans from URLs
• 🚀 Zero Configuration - Everything works out of the box

Quick Start

# Create a standard Next.js project
npx create-vibe-code-app my-awesome-project

# Create an AI-powered project with Vercel AI SDK
npx create-vibe-code-app my-ai-app --template vercel-ai

# List available templates
npx create-vibe-code-app --list-templates

# Create project with custom plan from URL
npx create-vibe-code-app my-project https://example.com/my-project-plan.md

# Navigate to your project and start developing
cd my-awesome-project
npm run dev

Installation

Global Installation (Recommended)

npm install -g create-vibe-code-app
create-vibe-code-app my-project

One-time Usage with npx

npx create-vibe-code-app my-project

Usage

Basic Usage

create-vibe-code-app <project-name>

Template Selection

# Create with specific template
create-vibe-code-app <project-name> --template <template-name>

# List all available templates
create-vibe-code-app --list-templates

Custom Project Plan

create-vibe-code-app <project-name> [plan-url] [options]

Available Templates

📦 next (Default)

A modern Next.js project with TypeScript, Tailwind CSS, and AI-assistant configuration.

Features:

• Next.js 14 with App Router
• TypeScript for type safety
• Tailwind CSS for styling
• ESLint & Prettier configuration
• Cursor AI assistant rules
• Structured project plan

Usage:

create-vibe-code-app my-project --template next
# or simply
create-vibe-code-app my-project

🤖 vercel-ai

Everything from the next template plus Vercel AI SDK integration with a working chat interface.

Additional Features:

• Pre-configured Vercel AI SDK
• OpenAI integration ready
• Working AI chat component
• Streaming chat responses
• AI-specific project plan
• Environment setup guide

Usage:

create-vibe-code-app my-ai-app --template vercel-ai

Setup for vercel-ai template:

# 1. Create project
npx create-vibe-code-app my-ai-app --template vercel-ai
cd my-ai-app

# 2. Set up environment variables
echo "OPENAI_API_KEY=your_openai_api_key_here" > .env.local

# 3. Start development
npm run dev

# 4. Visit http://localhost:3000 and try the AI chat!

CLI Options

Usage: create-vibe-code-app [project-name] [plan-source] [options]

Arguments:
  project-name              name of the project to create
  plan-source              optional URL to fetch project-plan.md from

Options:
  -t, --template <template>  template to use (choices: "next", "vercel-ai", default: "next")
  --list-templates          list all available templates
  -h, --help               display help for command
  -V, --version            display version number

Examples

Example 1: Standard Next.js Project

npx create-vibe-code-app my-blog
cd my-blog
npm run dev

Example 2: AI-Powered Chat Application

npx create-vibe-code-app ai-assistant --template vercel-ai
cd ai-assistant

# Add your OpenAI API key
echo "OPENAI_API_KEY=sk-..." > .env.local

npm run dev
# Visit http://localhost:3000 and start chatting with AI!

Example 3: Custom Project Plan

npx create-vibe-code-app my-saas https://example.com/saas-plan.md --template next
cd my-saas
# AI assistant will follow the custom plan

Example 4: Explore Available Templates

npx create-vibe-code-app --list-templates
# Output:
# 📋 Available templates:
#    • next
#    • vercel-ai

Project Structure

Standard Project (next template)

my-project/
├── src/
│   ├── components/
│   │   └── Header.tsx          # Example React component
│   ├── pages/
│   │   ├── _app.tsx            # Next.js app configuration
│   │   └── index.tsx           # Landing page
│   └── styles/
│       └── globals.css         # Global styles with Tailwind
├── .cursor/
│   └── rules/
│       └── project-guide.mdc   # AI assistant configuration
├── project-plan.md             # AI-readable project plan
└── [standard Next.js files...]

AI-Powered Project (vercel-ai template)

my-ai-project/
├── src/
│   ├── components/
│   │   ├── Header.tsx          # Example React component
│   │   └── AIChat.tsx          # AI chat interface ✨
│   ├── pages/
│   │   ├── api/
│   │   │   └── chat.ts         # AI chat endpoint ✨
│   │   ├── _app.tsx
│   │   └── index.tsx           # Landing page with AI demo
│   └── styles/
│       └── globals.css
├── .cursor/
│   └── rules/
│       └── project-guide.mdc   # AI-optimized configuration ✨
├── project-plan.md             # AI development plan ✨
└── [enhanced Next.js files...]

AI-Driven Development

Each project is optimized for AI-assisted development:

Project Plan (project-plan.md)

• Structured task list for AI assistants
• Template-specific development goals
• Clear instructions and requirements
• Progress tracking with checkboxes
• AI-friendly format and language

Cursor Configuration (.cursor/rules/)

• Pre-configured AI assistant rules using the new MDC format
• Project-specific context and workflow guidance
• Template-aware development guidelines
• Automatic task execution based on project-plan.md

Getting Started with AI

1. Open your project in Cursor or similar AI-enabled editor
2. Ask your AI assistant to read project-plan.md
3. Request implementation of specific tasks
4. AI will follow the structured plan and coding standards

For vercel-ai Template

The AI assistant is pre-configured to help with:

• Implementing advanced AI features
• Setting up function calling
• Adding multi-modal capabilities
• Optimizing AI model interactions
• Building RAG implementations

Environment Variables

vercel-ai Template Requirements

# Required: OpenAI API Key
OPENAI_API_KEY=your_openai_api_key_here

# Optional: Specify different model (defaults to gpt-3.5-turbo)
OPENAI_MODEL=gpt-4

# Optional: OpenAI organization (if you have multiple)
OPENAI_ORGANIZATION=your_org_id_here

Get your OpenAI API key at: https://platform.openai.com/api-keys

Available Scripts

In any created project, you can run:

• npm run dev - Start development server
• npm run build - Build for production
• npm run start - Start production server
• npm run lint - Run ESLint
• npm run lint:fix - Fix linting issues
• npm run format - Format code with Prettier
• npm run type-check - Check TypeScript types

Tech Stack

Base Stack (both templates)

• Next.js 14 - React framework with App Router
• TypeScript - Type-safe JavaScript
• Tailwind CSS - Utility-first CSS framework
• ESLint - Code linting and quality
• Prettier - Code formatting
• AI Configuration - .cursor/rules/ for AI assistants

Additional Stack (vercel-ai template)

• Vercel AI SDK - AI integration framework
• OpenAI API - Language model integration
• Streaming Support - Real-time AI responses
• Edge Runtime - Optimized performance

Remote Project Plans

Fetch project plans from any public URL:

# GitHub raw file
create-vibe-code-app my-ecommerce https://example.com/ecommerce-plan.md

# Any public markdown file  
create-vibe-code-app my-saas https://raw.githubusercontent.com/example/plans/main/saas.md --template vercel-ai

Requirements:

• URL must be publicly accessible
• Must return plain text/markdown content
• HTTP/HTTPS protocols only
• 5-second timeout with automatic fallback

Fallback: If URL fetch fails, the default template project plan is used.

Requirements

• Node.js >= 18.0.0
• npm or yarn or pnpm
• OpenAI API Key (for vercel-ai template)

Troubleshooting

Common Issues

"Template not found"

# List available templates
npx create-vibe-code-app --list-templates

# Use correct template name
npx create-vibe-code-app my-project --template vercel-ai

"Directory already exists"

# Choose a different name or remove existing directory
rm -rf my-project
create-vibe-code-app my-project

"Invalid project name"

# Use only letters, numbers, hyphens, and underscores
create-vibe-code-app my-valid-project-name

"AI chat not working" (vercel-ai template)

# Check if OpenAI API key is set
cat .env.local
# Should contain: OPENAI_API_KEY=sk-...

# Verify API key is valid at https://platform.openai.com/api-keys

"npm install failed"

# Check Node.js version and internet connection
node --version  # Should be >= 18.0.0
npm --version

Getting Help

• Check GitHub Issues
• Review generated project's README.md
• Ensure Node.js and npm are up to date
• For AI template issues, verify OpenAI API key setup

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Development

To work on create-vibe-code-app itself:

# Clone and setup
git clone https://github.com/AlubuArt/create-vibe-code-app.git
cd create-vibe-code-app
npm install

# Test CLI locally
node bin/create-vibe-app.js test-project

# Test with templates
node bin/create-vibe-app.js test-ai --template vercel-ai

# Run tests
npm test

# Run e2e validation
node scripts/e2e-test.js

License

MIT - see LICENSE file for details.

Related

• Next.js Documentation
• Tailwind CSS Documentation
• Vercel AI SDK Documentation
• OpenAI API Documentation
• Cursor AI Editor

Built with ❤️ for AI-driven development