🚧 WORK IN PROGRESS
This project is currently being built live on YouTube! Follow along and learn as I build this AI SaaS starter kit from scratch.
🎬 Watch the complete build series - Building AquaKit live!
📺 Subscribe to my YouTube channel to catch all the episodes
The complete AI SaaS starter kit with the ultimate developer stack - Next.js, TailwindCSS, Claude Code + Cursor, Better Auth, Convex, and Polar.sh. Ship your AI SaaS faster than ever.
View Demo
·
Report Bug
·
Request Feature
AquaKit is the ultimate AI SaaS starter kit designed to dramatically accelerate your development process. Built with today's most powerful developer tools - Next.js 15, TailwindCSS, Claude Code + Cursor, Better Auth, Convex, and Polar.sh - this starter kit eliminates months of setup and configuration, allowing you to focus on building your unique AI features and getting to market faster.
The entire stack is optimized for speed: From AI-powered development with Claude Code and Cursor, to real-time data with Convex including automated workflows with crons and durable functions, and seamless monetization with Polar.sh - every tool is chosen to maximize developer productivity and reduce time-to-market.
Key Features:
- 🚀 Speed-First Development: AI-powered coding with Claude Code + Cursor for 10x faster development
- 🔐 OAuth Authentication: Multiple provider support with GitHub, Google & Discord sign-in out of the box
- 👤 User Management: Complete user profiles with avatar support and session handling
- 🔑 Better Auth Integration: Secure authentication with Convex backend integration
- ⚡ Real-time Everything: Convex provides instant data synchronization and serverless functions
- 🤖 Background Jobs: Convex crons and durable functions for reliable AI processing, webhooks, and scheduled tasks
- 💰 Monetization Built-in: Polar.sh integration for subscriptions, payments, and customer management
- 🎨 Beautiful UI: TailwindCSS v4 with modern, responsive components and improved login forms
- 📱 Mobile-First: Responsive design that works perfectly on all devices
- 🔧 Type-Safe: Full TypeScript support with strict type checking
- ⚡ Lightning Fast: Turbopack for ultra-fast development and builds
- 🧠 AI-Ready: Pre-configured patterns for integrating any AI model or API
- 👤 Admin System: Role-based access control with debug tools and user management
- OAuth Provider Integration: Added GitHub, Google, and Discord sign-in functionality with comprehensive setup guides
- User Avatar System: Implemented dynamic avatar generation and external avatar URL support
- Improved Login UI: Enhanced login form with password visibility toggle and OAuth provider buttons
- Session Management: Robust session handling with loading states and error management
- Sidebar Navigation: Added user sidebar with profile information and navigation
- Dashboard Integration: Dedicated dashboard with improved user experience
- Theme Support: Integrated theme provider with consistent styling
- Component Library: Expanded UI components with Radix UI integration
- Role-Based Access Control: Complete admin system with environment variable configuration and automatic role initialization
- Admin Dashboard: Full-featured admin panel with user management, role assignment, and system overview
- Debug Tools: Advanced debugging utilities for OAuth provider linking, account diagnostics, and authentication testing
- User Management: Search users by email, promote/demote roles, view authentication methods, and track user activity
- Development Safety: Production-safe database operations with development-only destructive actions
- Reusable Components: AdminGuard and AdminPageLayout components for protecting admin content
- Quick Setup Script: Interactive
setup-admin.jsscript for easy admin configuration
- OAuth Setup Guides: Detailed step-by-step guides for GitHub, Google, and Discord OAuth configuration
- Environment Configuration: Comprehensive environment variable documentation with .env.example
- Admin System Documentation: Complete guides for admin setup, components, and best practices
- Production Deployment Guide: Step-by-step production deployment with real-world experience
- Quick Admin Setup: Streamlined admin configuration with QUICK_ADMIN_SETUP.md
- Developer Experience: Improved development workflows and debugging capabilities
To get a local copy up and running, follow these simple steps.
- Node.js (version 18 or higher)
- npm or your preferred package manager
To run this project, you will need to add the following environment variables to your .env.local file:
# Convex
NEXT_PUBLIC_CONVEX_URL="your-convex-deployment-url"
NEXT_PUBLIC_CONVEX_SITE_URL="http://localhost:3000"
CONVEX_SITE_URL=""
CONVEX_DEPLOYMENT=""
# Nextjs
SITE_URL="https://localhost:3000"
NEXT_PUBLIC_SITE_URL="https://localhost:3000"
# Better Auth
BETTER_AUTH_URL="http://localhost:3000"
# https://www.better-auth.com/docs/installation#set-environment-variables
BETTER_AUTH_SECRET=""
# === OAuth Provider Credentials ===
# GITHUB
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"
# Google
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"
# Discord
DISCORD_CLIENT_ID="your-discord-client-id"
DISCORD_CLIENT_SECRET="your-discord-client-secret"For OAuth authentication setup, refer to our detailed guides:
- GitHub OAuth Setup - Complete guide for setting up GitHub sign-in
- Google OAuth Setup - Complete guide for setting up Google sign-in
- Discord OAuth Setup - Complete guide for setting up Discord sign-in
All guides include step-by-step instructions for:
- Creating OAuth applications in each provider's developer console
- Configuring callback URLs and scopes
- Setting up environment variables in both your local environment and Convex deployment
- Security best practices and troubleshooting tips
For setting up admin users and accessing debug tools:
- Admin Setup Guide - Complete guide for configuring admin users and role-based access
The admin system provides:
- Role-based access control with environment variable configuration
- Admin dashboard with user management and debug tools
- Account linking diagnostics and testing utilities
- Development-safe database operations and user role management
- Clone the repo
git clone https://github.com/0xAquaWolf/AquaKit.git
- Install packages
npm install
- Start the development server
npm run dev
The application will be available at http://localhost:3000
AquaKit supports multiple OAuth providers for user authentication. Choose the providers you want to enable for your application:
| Provider | Setup Guide | Features |
|---|---|---|
| 🐙 GitHub | Setup Guide | Developer-focused authentication, access to GitHub profile |
| Setup Guide | Wide user base, reliable OAuth implementation | |
| 💬 Discord | Setup Guide | Gaming/community focused, rich user profiles |
Each guide provides:
- ✅ Step-by-step OAuth app creation
- ✅ Environment variable configuration (local & Convex)
- ✅ Security best practices
- ✅ Troubleshooting tips
| Feature | Setup Guide | Purpose |
|---|---|---|
| 🔧 Admin Panel Setup | Admin Setup Guide | Configure admin users, access debug tools, manage user roles |
| ⚡ Quick Admin Setup | Quick Admin Setup | Fast 5-step admin configuration with setup script |
| 🧩 Admin Components | Admin Components Guide | Use AdminGuard and AdminPageLayout for protected content |
| 🚀 Production Deployment | Production Guide | Complete production deployment with OAuth and environment setup |
The admin system includes:
- ✅ Environment variable-based admin configuration with interactive setup script
- ✅ Role-based access control with automatic initialization
- ✅ Comprehensive admin dashboard with user management, search, and role assignment
- ✅ Debug tools for OAuth provider linking, account diagnostics, and authentication testing
- ✅ Development-safe database operations with production safety checks
- ✅ Reusable AdminGuard and AdminPageLayout components for protecting content
- ✅ Complete production deployment guide with real-world OAuth configuration
Get admin access in just 5 minutes:
# Interactive admin setup script
node scripts/setup-admin.js
# Or follow the quick guide
# See: QUICK_ADMIN_SETUP.mdAfter following the setup guides, configure your environment variables:
# Local environment (.env.local)
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"
# Convex environment
npx convex env set GITHUB_CLIENT_ID "your-github-client-id"
npx convex env set GITHUB_CLIENT_SECRET "your-github-client-secret"AquaKit includes MCP (Model Context Protocol) server integration for enhanced AI development. Configure your editor to use the Convex MCP server:
Cursor Configuration:
Add to your cline_mcp_settings.json:
{
"mcpServers": {
"convex": {
"command": "npx",
"args": ["-y", "convex@latest", "mcp", "start"]
}
}
}Claude Code Configuration:
Add the MCP server and test with:
# Add the server
claude mcp add-json convex '{"type":"stdio","command":"npx","args":["convex","mcp","start"]}'
# Test the connection
claude mcp get convexnpm run dev- Start development server with Turbopacknpm run debug- Start development server with Node.js debugger enablednpm run build- Build for production with Turbopacknpm run start- Start production servernpm run lint- Run ESLintnpm run format- Format code with Prettiernpm run format:check- Check code formattingnpm run dev:backend- Start Convex development servernpm run dev:frontend- Start Next.js with HTTPS and Turbopack
This is a Next.js 15 application with App Router that integrates:
Authentication Stack:
- Better Auth with Convex integration (
@convex-dev/better-auth) - Auth client configured in
src/lib/auth-client.ts - Authentication routes in
src/app/api/auth/[...all]/route.ts - Convex auth configuration in
convex/auth.config.ts
Convex Integration:
- Convex backend with Better Auth plugin in
convex/convex.config.ts - Client provider wraps the app in
src/app/ConvexClientProvider.tsx - Schema definitions in
convex/schema.ts - HTTP endpoints in
convex/http.ts
Frontend Structure:
- Next.js App Router with TypeScript
- Tailwind CSS v4 for styling with custom configuration
- UI components in
src/components/ui/ - Path aliases:
@/*forsrc/*and@/convex/*forconvex/*
AquaKit dramatically reduces development time by providing a complete, pre-integrated stack. Instead of spending weeks configuring tools and services, you can:
- Ship in days, not months: Skip the tedious setup and focus on your unique AI features
- Build with AI assistance: Claude Code + Cursor provide intelligent code completion and generation
- Scale effortlessly: Real-time backend with Convex including background jobs with crons and durable functions
- Monetize immediately: Built-in payment and subscription system with Polar.sh
- Learn the modern stack: Perfect reference implementation of today's best developer tools
Perfect for:
- AI startups wanting to move fast
- Developers building AI-powered SaaS products
- Teams looking to modernize their development stack
- Anyone who wants to ship AI products faster
🎯 Project Mission: Complete Data Ownership
AquaKit's ultimate goal is to give you complete ownership of your data. We believe you should control your infrastructure and data, not be locked into proprietary cloud services. That's why we're building two versions to meet different needs while maintaining the same core principle.
The current implementation uses managed cloud services for rapid development and deployment:
- Convex for real-time backend, database, and background processing (crons, durable functions)
- Better Auth (package-based, not a service like Clerk)
- Polar.sh for payments and subscriptions
Perfect for: Getting to market quickly, prototyping, teams that prefer managed services
A completely self-hostable version for maximum data ownership:
- One-click Docker deployment to any server (Hetzner, DigitalOcean, Fly.io, etc.)
- Containerized Convex - self-hosted to own all your data while keeping the same functionality
- Better Auth
- Self-hosted payment processing
Perfect for: Complete data control, enterprise deployments, privacy-focused organizations
- Next.js 15 with App Router setup
- Convex backend integration
- Better Auth authentication system
- OAuth provider integration (GitHub, Google & Discord)
- User profile and avatar system
- Enhanced login forms with social sign-in
- Sidebar navigation and dashboard
- TypeScript configuration
- TailwindCSS v4 styling with theme support
- Component library with Radix UI
- Development tooling (ESLint, Prettier)
- Claude Code integration guide
- Cursor IDE configuration
- Comprehensive OAuth setup documentation (GitHub, Google, Discord)
- Environment configuration with .env.example
- Role-based access control with environment variable configuration
- Admin dashboard with comprehensive user management interface
- User management with search, role assignment, and activity tracking
- AdminGuard and AdminPageLayout reusable components
- Production-safe operations with development-only destructive actions
- Complete documentation (admin-setup.md, admin-components.md)
- Quick setup guide (QUICK_ADMIN_SETUP.md)
- Production deployment guide with real-world OAuth configuration
- Convex cron job examples for scheduled AI tasks
- Durable function examples for long-running AI processes
- Action retrier patterns for reliable external API calls
- Workflow examples using Convex's background processing
- AI integration patterns and examples
- Claude API integration templates
- Polar.sh subscription system integration
- Payment processing setup
- User dashboard and analytics
- Usage tracking and billing
- Docker containerization with one-click deployment
- Containerized Convex - self-hosted to maintain full data ownership while keeping all functionality
- Environment configuration wizard for easy setup
- Health monitoring and logging for self-hosted instances
- Backup and restore utilities for complete data control
- Component library expansion
- Testing suite implementation
- API rate limiting and usage tracking
- Performance optimization
- Mobile responsiveness improvements
- Migration tools (Cloud ↔ Self-hosted)
- Infrastructure templates for popular hosting providers
See the open issues for a full list of proposed features (and known issues).
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
Twitter / X - @0xAquaWolf
| Guide | Purpose | Time to Complete |
|---|---|---|
| Environment Setup | Configure development and production environments | 10 minutes |
| Production Deployment | Deploy to production with real-world OAuth setup | 30 minutes |
| Quick Admin Setup | Get admin access in 5 steps | 5 minutes |
| Provider | Setup Guide | Features |
|---|---|---|
| GitHub | GitHub OAuth Setup | Developer-focused authentication |
| Google OAuth Setup | Wide user base, reliable OAuth | |
| Discord | Discord OAuth Setup | Gaming/community focused |
| Guide | Purpose | Level |
|---|---|---|
| Admin Setup | Complete admin system configuration | Beginner |
| Admin Components | Use AdminGuard and AdminPageLayout | Intermediate |
All guides include step-by-step instructions, troubleshooting tips, and security best practices.
Wholeness and balanced Vibrations 🙌