A modern, production-ready starter kit for building full-stack applications with Next.js 16, Convex real-time database, Better Auth authentication, TypeScript, and shadcn/ui components.

📬 Join the Refactoring AI Newsletter

I teach developers how to ship their ideas in days with AI

Master modern full-stack development with AI-powered tools and techniques

✨ What You'll Learn:

🚀 I've taught over 50,000 developers to date.
🎯 Top 1% TypeScript engineers globally on GitHub.
🤖 Learn how to use AI coding agents like Claude Code effectively

→ Subscribe Now (It's Free!)

Perfect for: Rapidly prototyping full-stack applications, learning modern web development patterns, or starting your next SaaS project with a solid foundation.

• Features
• Quick Start
• Recommended Development Workflow
• Tech Stack
• Project Structure
• Documentation
• Development
• Testing
• Deployment
• Contributing
• License

• Authentication - Complete auth system with Better Auth + Convex integration

  • Email/password authentication (no verification required for quick setup)
  • Protected routes with middleware
  • Session management
  • Ready for OAuth providers (see Roadmap)

• Real-time Database - Powered by Convex

  • Serverless backend with zero infrastructure management
  • Automatic TypeScript generation
  • Real-time subscriptions out of the box
  • ACID transactions

• Modern UI Components - 20+ shadcn/ui components pre-installed

  • Buttons, Forms, Modals, Tables, Charts, Sidebar
  • Fully customizable with Tailwind CSS 4
  • Dark mode support with next-themes
  • Responsive design patterns

• Testing Infrastructure - Complete testing setup

  • Vitest for unit and integration tests
  • convex-test for isolated backend testing
  • Example tests included
  • Coverage reporting

• Developer Experience

  • TypeScript strict mode for type safety
  • ESLint configuration for code quality
  • Hot module replacement with Turbo
  • Parallel dev servers (frontend + backend)

Get up and running in 5 minutes:

• Node.js 18.x or later
• pnpm (recommended) or npm - the setup script will install pnpm if missing

# Clone the repository git clone https://github.com/robertguss/ai-starter-kit.git cd ai-starter-kit # Run the setup script (handles everything!) ./setup.sh

The setup script will:

1. Check and install prerequisites (including pnpm if missing)
2. Install all dependencies
3. Guide you through Convex authentication (opens browser)
4. Configure all environment variables automatically
5. Start the development servers

Note for Windows users: Run bash setup.sh in Git Bash or WSL.

# Clone the repository git clone https://github.com/robertguss/ai-starter-kit.git cd ai-starter-kit # Install dependencies pnpm install # Set up Convex (follow the prompts to create/link a project) npx convex dev # In a new terminal, set required environment variables npx convex env set BETTER_AUTH_SECRET $(openssl rand -base64 32) npx convex env set SITE_URL http://localhost:3000 # Add NEXT_PUBLIC_CONVEX_SITE_URL to .env.local (replace with your deployment name) echo "NEXT_PUBLIC_CONVEX_SITE_URL=https://YOUR-DEPLOYMENT.convex.site" >> .env.local # Start the development servers (frontend + backend) pnpm run dev

Open http://localhost:3000 in your browser. You should see the landing page!

Next steps:

1. Create an account at /signup
2. Log in and explore the dashboard
3. Check out the example Convex functions in convex/myFunctions.ts
4. Read the Setup Guide for detailed configuration

Tip: See docs/QUICK_START.md for a more detailed quick start guide with troubleshooting.

This starter kit is designed to work seamlessly with AI coding agents like Claude Code. For the best development experience, we recommend following the BMAD Method (Breakthrough Method for Agile AI Driven Development).

What is BMAD?

The BMAD Method is a comprehensive framework that combines human expertise with AI capabilities to build software more effectively. It provides:

• 19+ specialized AI agents and 50+ workflows for different development scenarios
• Three planning tracks that automatically adapt based on your project needs:
  • Quick Flow Track - Bug fixes and small features
  • BMad Method Track - Full products and platforms (recommended for this starter kit)
  • Enterprise Method Track - Complex systems with security and compliance needs

Why BMAD with this Starter Kit?

• Accelerates feature development while maintaining code quality
• Provides structured workflows for common tasks (auth, database, UI components)
• Helps AI agents understand your project structure and patterns
• Guides reflective thinking that brings out better architectural decisions

Getting Started with BMAD:

1. Review the BMAD Method documentation
2. Use the CLAUDE.md file in this repo (pre-configured for Claude Code)
3. Follow the BMad Method Track for adding new features to your application

Note: While BMAD is recommended, it's entirely optional. This starter kit works great with any development workflow or AI coding assistant.

• Next.js 16: Cutting-edge React framework with App Router, Server Components, and excellent DX
• Convex: Eliminates the complexity of traditional backends - no REST/GraphQL APIs to build, real-time by default
• Better Auth: Modern auth library with native Convex integration, avoiding external auth services
• shadcn/ui: Copy-paste components you own, built on Radix UI primitives for accessibility
• TypeScript: End-to-end type safety from database to frontend

ai-starter-kit/ ├── app/ # Next.js App Router │ ├── api/ # API routes (if any) │ ├── dashboard/ # Protected dashboard pages │ │ ├── page.tsx # Dashboard home with charts │ │ └── data.json # Sample data │ ├── login/ # Login page │ ├── signup/ # Signup page │ ├── ConvexClientProvider.tsx # Convex + Better Auth provider │ ├── layout.tsx # Root layout │ ├── page.tsx # Home/landing page │ └── globals.css # Global styles │ ├── components/ # React components │ ├── ui/ # shadcn/ui components (20+) │ ├── app-sidebar.tsx # Main application sidebar │ ├── login-form.tsx # Login form component │ ├── signup-form.tsx # Signup form component │ └── data-table.tsx # Reusable data table │ ├── convex/ # Convex backend │ ├── _generated/ # Auto-generated types & API │ ├── auth.config.ts # Better Auth configuration │ ├── auth.ts # Auth helper functions │ ├── http.ts # HTTP routes (auth endpoints) │ ├── schema.ts # Database schema │ ├── myFunctions.ts # Example Convex functions │ ├── myFunctions.test.ts # Example tests │ ├── test.setup.ts # Test configuration │ └── TESTING.md # Testing documentation │ ├── lib/ # Shared utilities │ ├── auth-client.ts # Better Auth React client │ └── utils.ts # Helper functions (cn, etc.) │ ├── hooks/ # React hooks │ └── use-mobile.ts # Mobile detection hook │ ├── docs/ # Documentation │ ├── QUICK_START.md # 5-minute setup guide │ ├── SETUP.md # Detailed setup instructions │ ├── ARCHITECTURE.md # System architecture │ ├── DEVELOPMENT.md # Development workflows │ ├── DEPLOYMENT.md # Production deployment │ ├── API.md # API documentation │ ├── DATABASE.md # Database schema guide │ ├── AUTHENTICATION.md # Auth flow details │ ├── TROUBLESHOOTING.md # Common issues & solutions │ └── IDE_TOOLS.md # IDE enhancement tools │ ├── .github/ # GitHub templates │ ├── ISSUE_TEMPLATE/ # Issue templates │ └── PULL_REQUEST_TEMPLATE.md # PR template │ ├── middleware.ts # Next.js middleware (route protection) ├── CLAUDE.md # Claude AI development guide ├── CONTRIBUTING.md # Contribution guidelines ├── CODE_OF_CONDUCT.md # Code of conduct ├── CHANGELOG.md # Version history ├── ROADMAP.md # Future plans └── LICENSE # MIT License 

Comprehensive guides for all aspects of the starter kit:

• Quick Start Guide - Get running in 5 minutes
• Detailed Setup - Complete installation & configuration
• Architecture Overview - How everything fits together

• Development Guide - Adding features, modifying schema
• API Reference - Convex functions documentation
• Database Guide - Schema, indexes, and patterns
• Authentication - Auth flows and customization

• Deployment Guide - Deploy to production (Vercel)
• Troubleshooting - Common issues and solutions
• IDE Tools - Optional development enhancements

# Development pnpm run dev # Run both frontend and backend in parallel pnpm run dev:frontend # Run Next.js only pnpm run dev:backend # Run Convex only pnpm run predev # Convex dev + auto-open dashboard # Building pnpm run build # Build Next.js for production pnpm run start # Start production server # Code Quality pnpm run lint # Run ESLint # Testing pnpm run test # Run tests in watch mode pnpm run test:once # Run tests once pnpm run test:debug # Debug tests with inspector pnpm run test:coverage # Run with coverage report

# Add a new shadcn/ui component npx shadcn@latest add [component-name] # Generate Convex types (after schema changes) npx convex codegen # Open Convex dashboard npx convex dashboard

Create a .env.local file for Next.js (auto-generated by Convex):

# Auto-generated by `npx convex dev` NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud # IMPORTANT: Set this to your Convex HTTP endpoint (.convex.site, NOT .convex.cloud) # This is used to proxy auth requests from Next.js to Convex NEXT_PUBLIC_CONVEX_SITE_URL=https://your-deployment.convex.site

Warning: NEXT_PUBLIC_CONVEX_SITE_URL must point to your Convex site URL (ending in .convex.site), NOT localhost:3000. Setting it to localhost:3000 will cause an infinite loop and 500 errors on auth endpoints.

Set Convex environment variables:

npx convex env set BETTER_AUTH_SECRET $(openssl rand -base64 32) npx convex env set SITE_URL http://localhost:3000

See .env.example for all available variables.

This starter includes a complete testing setup with Vitest and convex-test:

# Run tests in watch mode pnpm run test # Run tests once (CI mode) pnpm run test:once # Run with coverage pnpm run test:coverage

Example test structure:

• convex/myFunctions.test.ts - Example Convex function tests
• Tests run in isolated environment with mock database
• See convex/TESTING.md for comprehensive testing guide

Key patterns:

import { convexTest } from "convex-test"; import { modules } from "./test.setup"; import schema from "./schema"; it("should test something", async () => { const t = convexTest(schema, modules); const result = await t.query(api.myFunctions.listNumbers, { count: 10 }); expect(result.numbers).toEqual([]); });

1. Push to GitHub

   git push origin main

2. Deploy Frontend

   • Go to vercel.com
   • Import your GitHub repository
   • Vercel will auto-detect Next.js

3. Deploy Backend

   npx convex deploy

4. Set Production Environment Variables

   npx convex env set BETTER_AUTH_SECRET $(openssl rand -base64 32) --prod npx convex env set SITE_URL https://your-domain.vercel.app --prod

5. Update Vercel Environment Variables

   • Add NEXT_PUBLIC_CONVEX_URL with your production Convex URL

See docs/DEPLOYMENT.md for detailed deployment instructions, custom domains, and other platforms.

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (pnpm run test:once)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

See ROADMAP.md for planned features and enhancements, including:

• OAuth providers (Google, GitHub)
• Email verification flow
• Password reset functionality
• User profile management
• Additional example components
• And more!

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Contributing: Contribution Guidelines

This project is licensed under the MIT License - see the LICENSE file for details.

Built with amazing open-source technologies:

• Next.js - The React Framework
• Convex - The reactive backend
• Better Auth - Authentication for TypeScript
• shadcn/ui - Beautifully designed components
• Tailwind CSS - Utility-first CSS framework
• Radix UI - Unstyled, accessible components

Made with ❤️ by Robert Guss

If this starter kit helped you, consider giving it a ⭐️ on GitHub!