Vibe Coding Starter Kit

Build Your Business In Hours Not Weeks

🤖 AI Assistant Instructions

IMPORTANT: Before making any changes to this codebase, you MUST:

1. Read the documentation in the docs/ folder to understand the project architecture
2. Follow the Cursor rules defined in .cursor/rules/ - these are mandatory coding standards

Quick Start for AI Assistants

1. Start with docs/00-welcome/START-HERE.md
2. Review docs/01-getting-started/ for project structure
3. Check .cursor/rules/ for coding standards
4. Use the existing UI components from src/components/ui/

Key Principles

• Use existing components - Don't create new UI primitives, use shadcn/ui components in src/components/ui/
• Follow design tokens - Use CSS variables like bg-primary, text-foreground, etc.
• Validate inputs - Use Zod schemas for all form data
• Handle errors - Every async operation needs error handling
• Type safety - No any types, use proper TypeScript

---

🚀 Getting Started

Prerequisites

Before you begin, you'll need these tools installed:

1. Terminal (Command Line) - This is where you'll type commands

   What is Terminal? It's a text-based way to control your computer. Think of it like texting your computer to tell it what to do!

   How to open Terminal:

   • Mac:
     1. Press Cmd + Space (Command key + Space bar)
     2. Type "Terminal"
     3. Press Enter
     4. A black or white window will open - that's Terminal!
   • Windows:
     1. Press Windows + R keys together
     2. Type "cmd"
     3. Press Enter
     4. Or search "Command Prompt" in the Start menu
   • Linux:
     1. Press Ctrl + Alt + T keys together
     2. Or search "Terminal" in your applications menu

   Using Terminal for the first time?

   • You'll see a prompt (text ending with $ or >)
   • Type commands and press Enter to run them
   • You can copy commands from this guide and paste them (right-click or Cmd/Ctrl+V)
   • If something goes wrong, you can close Terminal and open it again

2. Node.js and npm (if you don't have them):

   What is npm? It's a tool that comes with Node.js. It helps install code libraries (called "packages") that your project needs. Think of it like an app store for code!

   How to install:

   Option 1: Easy Install (Recommended for beginners)

   • Windows/Mac:
     1. Open your web browser
     2. Go to nodejs.org
     3. Click the big green "Download" button (it automatically picks the right version)
     4. Open the downloaded file
     5. Follow the installer - just click "Next" through all the steps (the default options are fine)
     6. After installation, close and reopen Terminal (important!)

   Option 2: Using Homebrew (Mac only, if you already have it)

   • If you already installed Homebrew before:
     1. Open Terminal (see instructions above)
     2. Type: brew install node
     3. Press Enter
     4. Wait for it to finish (it might ask for your password - that's normal)

   Option 3: Linux

   • Open Terminal
   • Type one of these (copy and paste):
     • Ubuntu/Debian: sudo apt-get install nodejs npm
     • Red Hat/CentOS: sudo yum install nodejs npm
   • Press Enter
   • Enter your password when asked (you won't see the password as you type - that's normal)

   Verify it worked:

   1. Open Terminal (see instructions above)
   2. Type: node --version and press Enter
   3. Type: npm --version and press Enter
   4. You should see version numbers (like v20.10.0 and 10.2.3)
   5. If you see "command not found" or an error:
      • Close Terminal completely
      • Open Terminal again
      • Try the commands again
      • If it still doesn't work, make sure you completed the installation

3. Git (for saving your work):

   • The setup script will check and help you install this
   • See docs/01-getting-started/github-setup.md for detailed instructions

4. Cursor IDE (recommended):

   • Download from cursor.sh
   • This is where you'll work with the AI assistant

Installation

Step 1: Open Terminal and navigate to your project

1. Open Terminal (see instructions above if you need help)
2. You need to "navigate" to your project folder. Here's how:
   • Mac/Linux: Type cd (with a space), then drag your project folder from Finder into Terminal, then press Enter
   • Windows: Type cd (with a space), then drag your project folder into Command Prompt, then press Enter
   • Or manually type: cd path/to/your/project (replace with your actual folder path)
3. You should see your project folder name in the Terminal prompt - that means you're in the right place!

Step 2: Install project dependencies

1. In Terminal, type: npm install
2. Press Enter
3. Wait for it to finish (this might take 2-5 minutes the first time)
4. You'll see a lot of text scrolling - that's normal! It's downloading all the code libraries your project needs
5. When it's done, you'll see your prompt again (the $ or >)

Step 3: Run the setup script

1. In Terminal, type: npm run setup
2. Press Enter
3. The friendly setup script will:
   • Check if you have the tools you need (Git, Supabase CLI)
   • Ask if you want to install missing tools (type "yes" or "y" if you want help)
   • Set up your database (if you're using Supabase)
   • Guide you through connecting to GitHub
   • Explain everything in simple terms!
4. Follow the prompts - it will ask you questions and guide you through everything

Step 4: Start developing

1. In Terminal, type: npm run dev
2. Press Enter
3. Wait a moment - you'll see "Ready" when it's done
4. Your browser might automatically open, or you can manually go to: http://localhost:3000
5. Check out /getting-started for AI prompts and guides

💡 Tip: Keep Terminal open while you're developing. You'll see helpful messages there!

Build for Production

npm run build
npm start

This creates an optimized version of your app ready to deploy.

Project Structure

src/
├── app/              # Next.js App Router pages
├── components/       # React components
│   └── ui/          # shadcn/ui components
├── config/          # Configuration files
├── hooks/           # Custom React hooks
├── lib/             # Utility libraries
├── styles/          # CSS and brand styles
├── types/           # TypeScript types
└── utils/           # Utility functions

docs/                # Project documentation
.cursor/rules/       # AI coding rules (MUST FOLLOW)

📚 Documentation

Everything you need is in the docs/ folder:

• 00-welcome/ - Start here! Welcome guide and overview
• 01-getting-started/ - Project setup, structure, and GitHub setup
• 02-building/ - How to add features and pages
• 03-ai-configuration/ - Setting up Cursor AI
• 04-deployment/ - How to deploy your app
• 05-reference/ - Technical details and API reference

Key Guides

• GitHub Setup: docs/01-getting-started/github-setup.md - Connect your project to GitHub
• Stripe Setup: Visit /getting-started in your app - Complete guide with AI prompts
• Project Structure: docs/01-getting-started/project-structure.md - Understand your codebase

🛠️ Tech Stack

• Framework: Next.js 15 (App Router) - Modern React framework
• Styling: Tailwind CSS 4 + shadcn/ui - Beautiful, accessible components
• Language: TypeScript - Type-safe JavaScript
• Validation: Zod - Form and data validation
• Icons: Lucide React - Beautiful icon library

🎯 Key Features

Setup & Configuration

• Automated Setup Script - npm run setup handles everything
• GitHub Integration - Automatic .gitignore and setup guide
• Environment Variables - Secure API key management

Integrations

• Supabase - Database and authentication (with migration support)
• Stripe - Payments (with comprehensive setup guide)
• Resend - Email sending
• PostHog - Analytics
• N8N - Workflow automation
• Google Analytics - Website tracking

Developer Experience

• AI Assistant Ready - Cursor IDE rules for consistent code
• Getting Started Page - Built-in guide with AI prompts
• Comprehensive Docs - Everything explained for beginners
• Type Safety - TypeScript prevents errors before they happen

💡 Working with AI

This project is designed to work with Cursor AI:

1. Open Cursor IDE - The AI reads the rules in .cursor/rules/
2. Visit /getting-started - Copy ready-to-use prompts
3. Ask the AI - Tell it what you want to build
4. Review changes - The AI will show you what it created
5. Save your work - Commit and push to GitHub regularly

The AI knows your project structure and will follow best practices automatically!

🆘 Need Help?

• Check the docs - Start with docs/00-welcome/START-HERE.md
• Visit /getting-started - Built-in guide in your app
• Ask the AI - Cursor AI assistant is there to help
• GitHub Setup - See docs/01-getting-started/github-setup.md
• Stripe Setup - See /getting-started in your app
• Stripe Webhooks (Local Testing) - See docs/STRIPE-WEBHOOK-SETUP.md

📝 Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run start - Start production server
• npm run setup - Run setup script (database, tools, GitHub)
• npm run lint - Check code quality

🎓 For Beginners

First time coding? You're in the right place! We've designed everything to be beginner-friendly.

Common Questions

Q: What is Terminal/Command Line?

• It's a text-based way to control your computer
• Instead of clicking buttons, you type commands
• It might look scary, but it's actually very powerful and useful
• You'll get comfortable with it quickly!

Q: What if I make a mistake in Terminal?

• Don't worry! Most mistakes won't break anything
• If something goes wrong, you can usually just close and reopen Terminal
• The setup script will guide you and catch common mistakes

Q: What is npm?

• npm stands for "Node Package Manager"
• It's a tool that comes with Node.js
• It helps install code libraries (called "packages") that your project needs
• Think of it like an app store, but for code libraries
• When you run npm install, it reads a file called package.json and downloads everything your project needs

Q: What is Git/GitHub?

• Git helps you save and track changes to your code (like a time machine for your project)
• GitHub stores your code online (like a cloud backup)
• The setup script will help you set this up - don't worry!

Q: I'm stuck! What do I do?

• Check the docs/ folder - everything is explained there
• Ask the AI assistant in Cursor - it knows your project!
• Visit /getting-started in your app for helpful guides
• Remember: everyone starts somewhere, and it's okay to ask for help!

Tips for Success

• Start simple - Build one feature at a time
• Save your work - Set up GitHub to backup your code (the setup script will help!)
• Ask the AI - The AI assistant in Cursor can help you build features
• Read the docs - They're written for beginners like you
• Don't be afraid to experiment - You can't break anything permanently
• Take breaks - Learning to code takes time, and that's okay!

📄 License

Private - All rights reserved.