⚡ Vibe Stack

Stop fixing AI-generated bugs. Start shipping production apps.

A Next.js 15 + Supabase boilerplate with 22 .mdc architecture rules that physically prevent AI coding assistants from hallucinating insecure auth, deprecated packages, and broken patterns.

The problem: AI models generate code that compiles perfectly but ships critical vulnerabilities — getSession() instead of getUser(), synchronous params that crash in Next.js 15, missing RLS policies that expose your database. These bugs are invisible until production.

The fix: Architecture rules that override the AI's training data. When a rule says "NEVER use getSession()", the model is constrained to generate the secure pattern. Every time.

---

🏗️ What's Inside

22 Architecture Rules (.cursor/rules/)

Rule File	What It Prevents
supabase-auth-security.mdc	Bans getSession(), enforces getUser() for JWT verification
nextjs15-params.mdc	Prevents synchronous params access (the #1 Next.js 15 breaking change)
supabase-ssr-only.mdc	Blocks deprecated @supabase/auth-helpers-nextjs imports
security.mdc	OWASP Top 10 enforcement with rate limiting examples
stripe-payments.mdc	Server-only Stripe, webhook signature verification
typescript-strict.mdc	Bans any, enforces Zod validation at every boundary
performance.mdc	Parallel fetching, N+1 prevention, dynamic imports
server-vs-client-components.mdc	Prevents unnecessary 'use client' overuse
project-context.mdc	Global context rule (always active) — maps the full architecture
server-actions.mdc	Zod validation + structured error returns
error-handling.mdc	Mandates error boundaries and loading states
supabase-rls.mdc	Enforces Row Level Security on every table
shadcn-patterns.mdc	Form patterns with react-hook-form + Zod
api-design.mdc	Standard Route Handler patterns with auth checks
testing.mdc	Vitest + Playwright testing strategy
git-conventions.mdc	Conventional commits + PR structure
ai-collaboration.mdc	The 3-stage agentic loop (Plan → Implement → Verify)
file-naming.mdc	File/directory naming conventions + import order
database-design.mdc	Schema patterns, UUID keys, RLS templates
env-management.mdc	Secret classification + NEXT_PUBLIC_ safety rules
hydration-safety.mdc	Prevents hydration mismatches (Math.random, window, Date)
caching-revalidation.mdc	Correct caching defaults + revalidatePath after mutations

4 MCP Integrations (.cursor/mcp.json)

Your AI doesn't just write code — it reads your GitHub PRs, inspects your Supabase schema, navigates your filesystem, and browses your running app.

• GitHub MCP — AI reads PRs, commit history, and issues
• Supabase MCP — AI inspects your database schema and RLS policies
• Filesystem MCP — AI navigates your project structure
• Browser MCP — AI takes screenshots and tests your running app

Production Application Layer

src/
├── app/
│   ├── (auth)/              # Login + Signup with Zod validation
│   ├── auth/confirm/        # PKCE email verification callback
│   ├── dashboard/           # Protected dashboard (server-side auth)
│   ├── api/webhooks/stripe/ # Stripe webhook handler
│   ├── page.tsx             # Dark-mode landing page
│   ├── error.tsx            # Global error boundary
│   ├── loading.tsx          # Global loading state
│   └── not-found.tsx        # Custom 404
├── lib/
│   ├── supabase/            # Server + client factories + middleware
│   ├── stripe/              # Checkout + portal utilities
│   ├── email/               # Resend templates (welcome, password reset)
│   ├── env.ts               # Type-safe environment variables
│   └── utils.ts             # cn() helper + utilities
├── types/                   # ActionResponse, UserProfile, PaginatedResponse
└── middleware.ts             # Session refresh

3 n8n Automation Workflows

Ready-to-import JSON templates that replace a $200/month marketing stack:

• GitHub Star → Lead Capture — Auto-emails stargazers with your paid product link
• Dev.to → Social Cross-Post — Auto-tweets new articles
• Gumroad Sale → CRM + Thank You — Tracks customers in Notion, sends onboarding email

---

🚀 Quick Start

git clone https://github.com/vibestackdev/vibe-stack.git
cd vibe-stack
npm install
cp .env.example .env.local
# Add your Supabase URL + anon key to .env.local
npm run dev

Open in Cursor and start building. The rules activate automatically.

Read docs/VIBE-CODING.md for the complete prompting framework.

---

📚 Documentation

Doc	Description
VIBE-CODING.md	The 3-stage agentic loop for AI-assisted development
ARCHITECTURE.md	8 Architecture Decision Records — explains every "why"
MCP-SETUP.md	Step-by-step MCP server setup guide

---

🔥 How It Compares

Feature	Vibe Stack	ShipFast ($169)	MakerKit ($299)
AI Architecture Rules	✅ 22 rules	❌	❌
MCP Integrations	✅ 4 servers	❌	❌
n8n Automations	✅ 3 workflows	❌	❌
Next.js 15 + React 19	✅	✅	✅
Supabase SSR Auth	✅ Secure	✅	✅
Stripe Payments	✅	✅	✅
Time to First Feature	20 min	3-4 hours	1-2 days
Documentation to Read	3 short docs	400+ pages	200+ pages
Learning Curve	Your AI reads the rules	You read their docs	You read their docs

---

💎 Want the Complete System?

This repo is the free foundation. The extended version includes the full boilerplate, Stripe integration, email templates, n8n workflows, and the Vibe Coding Masterclass.

→ Get the AI Builder's Complete System

Tier	What You Get	Price
Rules Pack	All 22 .mdc rules + Vibe Coding guide	$29
Builder System	Rules + 4 MCP configs + Architecture docs + SQL migrations	$69
Complete Vault	Everything + full boilerplate + Stripe + email + Masterclass	$149

---

🤝 Contributing

Found a hallucination pattern I'm missing? Open an issue describing the incorrect pattern the AI generates and the correct fix. I'll add it as a new rule.

📄 License

MIT — use it however you want.

---

Built by VibeStack — Architecture intelligence for AI-assisted development.