👑 Queen SaaS

Production-ready Next.js SaaS template with authentication, billing, multi-tenancy, and AI chat - built with modern best practices.

🚀 Quick Start

npx queen-saas my-saas-app
cd my-saas-app
npm run dev

Visit http://localhost:3000 and check the Setup Guide page for detailed configuration instructions.

✨ What's Included

Core Features

• ✅ Authentication - NextAuth v5 with email/password + OAuth (Google, GitHub)
• ✅ Multi-Tenancy - Organizations with member roles (Owner, Admin, Member)
• ✅ Billing - Stripe subscriptions with webhooks and customer portal
• ✅ AI Chat Widget - Floating assistant powered by OpenAI and Vercel AI SDK
• ✅ Database - Prisma ORM (SQLite dev / PostgreSQL prod)
• ✅ Email - Resend integration with React Email templates
• ✅ Admin Dashboard - Analytics, revenue tracking, user management
• ✅ Setup Guide - In-app configuration guide for local and production

UI/UX

• ✅ Shadcn UI - Beautiful, accessible components
• ✅ Tailwind CSS v4 - Latest styling with modern configuration
• ✅ Framer Motion - Smooth animations and transitions
• ✅ Responsive Design - Mobile-first, works everywhere
• ✅ Dark Mode Ready - Easy to enable (commented in code)

Developer Experience

• ✅ TypeScript - Full type safety throughout
• ✅ ESLint + Prettier - Code quality and formatting
• ✅ Testing Setup - Jest + React Testing Library
• ✅ Error Tracking - Sentry integration (optional)
• ✅ API Routes - RESTful endpoints with authentication
• ✅ Middleware - Route protection and redirects

Deployment

• ✅ Vercel-Optimized - Deploy in 30 seconds
• ✅ Environment Variables - Comprehensive .env.example
• ✅ Database Migrations - Prisma migrations ready
• ✅ Production Ready - Zero warnings, fully tested

📚 Tech Stack

| Category | Technology | |----------|------------| | Framework | Next.js 15 (App Router) | | Language | TypeScript 5.7 | | Styling | Tailwind CSS v4 | | UI Components | Shadcn + Radix UI | | Database | Prisma (SQLite/PostgreSQL) | | Auth | NextAuth v5 | | Payments | Stripe | | Email | Resend + React Email | | AI | OpenAI + Vercel AI SDK | | Animations | Framer Motion | | Deployment | Vercel |

🎯 Getting Started

1. Create Your Project

npx queen-saas my-saas-app
cd my-saas-app

The CLI will:

• Copy all template files
• Install dependencies
• Initialize the database
• Create .env.local from .env.example

2. Configure Environment Variables

Edit .env.local with your API keys:

# Generate this with: openssl rand -base64 32
NEXTAUTH_SECRET="your-secret-here"
NEXTAUTH_URL="http://localhost:3000"

# Get from https://dashboard.stripe.com/apikeys
STRIPE_SECRET_KEY="sk_test_..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

# Product/Price IDs from Stripe Dashboard
STRIPE_HOBBY_PRICE_ID="price_..."
STRIPE_PRO_PRICE_ID="price_..."
STRIPE_ENTERPRISE_PRICE_ID="price_..."

# Get from https://resend.com
RESEND_API_KEY="re_..."
EMAIL_FROM="[email protected]"

# (Optional) Get from https://platform.openai.com/api-keys
OPENAI_API_KEY="sk-..."

# Database (SQLite for dev, PostgreSQL for prod)
DATABASE_URL="file:./prisma/db.sqlite"

3. Seed Admin User (Optional)

npm run db:seed

This creates an admin user:

• Email: [email protected]
• Password: admin123

⚠️ Change this password immediately after first login!

4. Start Development

npm run dev

Visit http://localhost:3000

5. Follow the Setup Guide

Once running, visit /setup in your app for:

• Local Development Tab - Step-by-step local setup
• Production Tab - Complete deployment guide

🏗️ Project Structure

├── app/                      # Next.js App Router
│   ├── (auth)/              # Authentication pages
│   │   ├── login/
│   │   └── signup/
│   ├── (dashboard)/         # Protected dashboard
│   │   ├── dashboard/       # Main dashboard
│   │   ├── admin/           # Analytics (admin only)
│   │   ├── settings/        # User/org settings
│   │   └── setup/           # Setup guide
│   ├── api/                 # API routes
│   │   ├── auth/            # NextAuth
│   │   ├── billing/         # Stripe checkout/portal
│   │   ├── chat/            # AI chat endpoint
│   │   ├── invites/         # Team invitations
│   │   └── webhooks/        # Stripe webhooks
│   └── page.tsx             # Landing page
├── components/              # React components
│   ├── ui/                  # Shadcn components
│   ├── admin/               # Admin-specific
│   ├── animations/          # Framer Motion
│   └── dashboard/           # Dashboard components
├── lib/                     # Core utilities
│   ├── prisma.ts           # Database client
│   ├── stripe.ts           # Stripe client
│   ├── email.ts            # Email service
│   └── auth.ts             # Auth utilities
├── prisma/                 # Database
│   ├── schema.prisma       # Database schema
│   └── seed.ts             # Seed script
├── emails/                 # React Email templates
├── auth.ts                 # NextAuth config
└── middleware.ts           # Auth middleware

🛠️ Development Commands

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 type-check   # Run TypeScript check
npm test             # Run tests
npm run db:generate  # Generate Prisma client
npm run db:push      # Push schema changes (dev)
npm run db:migrate   # Create migration (prod)
npm run db:studio    # Open Prisma Studio
npm run db:seed      # Seed database

💳 Stripe Setup

Development (Test Mode)

1. Get test API keys from Stripe Dashboard
2. Create test products (Hobby, Pro, Enterprise)
3. Install Stripe CLI: brew install stripe/stripe-cli/stripe
4. Forward webhooks:

   stripe listen --forward-to localhost:3000/api/webhooks/stripe

5. Copy webhook secret to .env.local

Production

1. Activate your Stripe account
2. Switch to live mode API keys
3. Create webhook endpoint: https://yourdomain.com/api/webhooks/stripe
4. Select events: checkout.session.completed, customer.subscription.updated, customer.subscription.deleted
5. Update environment variables in Vercel

📧 Email Setup

Development

Use Resend's test domain:

EMAIL_FROM="[email protected]"

Production

1. Add your domain in Resend Dashboard
2. Add DNS records (SPF, DKIM, DMARC)
3. Wait for verification (24-48 hours)
4. Update EMAIL_FROM with your domain

🚀 Deployment (Vercel)

Option 1: Vercel Dashboard

1. Push code to GitHub/GitLab
2. Import project at vercel.com/new
3. Add environment variables
4. Deploy!

Option 2: Vercel CLI

npm i -g vercel
vercel

Production Checklist

• [ ] Update DATABASE_URL to PostgreSQL
• [ ] Set all environment variables
• [ ] Run npx prisma migrate deploy
• [ ] Configure Stripe production webhooks
• [ ] Verify email domain
• [ ] Update OAuth callback URLs
• [ ] Set up custom domain
• [ ] Enable Vercel Analytics (optional)

🎨 Customization

Branding

1. Metadata - Update app/layout.tsx:

   export const metadata: Metadata = {
     title: 'Your SaaS Name',
     description: 'Your description',
   };

2. Colors - Edit app/globals.css and tailwind.config.js

3. Logo - Replace in navigation components

Landing Page

Edit app/page.tsx - look for TODO: comments marking placeholder content.

Features

Build your features in app/(dashboard)/ - all infrastructure is ready:

• Authentication ✅
• Database with Prisma ✅
• Multi-tenancy ✅
• Billing ✅
• Email ✅
• Admin panel ✅

💬 AI Chat Widget

The floating chat button appears on all dashboard pages. Customize it by:

1. System Prompt - Edit app/api/chat/route.ts:

   system: 'Your custom instructions here...'

2. Model - Change in app/api/chat/route.ts:

   model: openai('gpt-4o-mini') // or gpt-4o, gpt-4-turbo

3. Styling - Edit components/assistant-chat-provider.tsx

4. Disable - Remove <AssistantChatProvider /> from app/layout.tsx

🔒 Security Best Practices

• ✅ All API routes are protected with authentication
• ✅ Organization data is isolated by organizationId
• ✅ Role-based access control for admin features
• ✅ Input validation with Zod schemas
• ✅ CSRF protection via NextAuth
• ✅ Secure password hashing with bcrypt
• ✅ Environment variables never exposed to client
• ✅ Stripe webhook signature verification

📊 Database Schema

Key Models

• User - Authentication and profile
• Organization - Multi-tenant organizations
• Membership - User-Organization relationships with roles
• Subscription - Stripe subscriptions linked to organizations
• Invitation - Team member invitations

Relationships

User ← Membership → Organization → Subscription
                                 → Invitation

All queries filter by organizationId to ensure data isolation.

🧪 Testing

npm test              # Run all tests
npm run test:watch    # Watch mode

Tests are located next to components:

• *.test.ts - Unit tests
• *.test.tsx - Component tests

🐛 Error Tracking (Optional)

Sentry Setup

1. Create project at sentry.io
2. Add to .env.local:

   SENTRY_DSN="https://[email protected]/..."
   NEXT_PUBLIC_SENTRY_DSN="https://[email protected]/..."

Sentry automatically captures:

• Unhandled errors
• API route errors
• Client-side exceptions
• Performance issues

📖 Additional Resources

• Next.js Documentation
• Prisma Documentation
• NextAuth Documentation
• Stripe Documentation
• Tailwind CSS Documentation

🤝 Contributing

This is a template - fork it and make it your own! No contributions needed.

📄 License

MIT License - see LICENSE file for details.

💬 Support

• 📧 Issues: GitHub Issues
• 📖 Docs: Check /setup page in your running app
• 💡 Questions: Open a discussion

Built with ❤️ by Queen Claude

Ready to build your SaaS?

npx queen-saas my-saas-app