Quick Start

Quick Start Guide

Get Solo Kit up and running in 5 minutes. This guide gets you from zero to a working SaaS application with database, authentication, and more.

⚡ Prerequisites

Before starting, ensure you have:

• Node.js 18+ (download here)
• pnpm - npm install -g pnpm
• Git - For version control
• Code editor - VS Code, WebStorm, or your preferred editor

🚀 1. Clone and Install

# Clone the repository
git clone https://github.com/your-username/solo-kit.git
cd solo-kit

# Install dependencies
pnpm install

This installs all dependencies for web, mobile, and shared packages in one command.

🗄️ 2. Set Up Convex Backend

Set up your Convex backend (free tier available):

Initialize Convex

# Initialize Convex in your project
npx convex dev

This will:

1. Create a Convex account if you don't have one
2. Set up a new Convex project
3. Add NEXT_PUBLIC_CONVEX_URL to your .env.local

⚙️ 3. Configure Environment

Create your environment file:

# Copy the example environment file
cp .env.example .env.local

Your .env.local should contain:

# Required - Your Convex deployment URL (added automatically by npx convex dev)
NEXT_PUBLIC_CONVEX_URL="https://your-project.convex.cloud"

# Optional - For admin features (use your email)
ADMIN_EMAIL="your-email@example.com"

🏗️ 4. Initialize Backend

The Convex backend initializes automatically when you run npx convex dev. Your schema is defined in the convex/ directory and syncs automatically.

🎉 5. Start Development

pnpm dev

Your app is now running at:

• Web App: http://localhost:3020
• Debug Panel: http://localhost:3020/debug

🎯 What You Get Out of the Box

Visit your running application and you'll see:

🏠 Landing Page

• Professional marketing site
• Pricing tables
• Feature highlights
• Responsive design
• Dark mode support

🔐 Authentication

• Sign up/Login pages ready to use
• OAuth providers (GitHub, Google) - configure in auth settings
• Email/password authentication
• Protected routes and dashboard

📊 Dashboard

• User dashboard with profile management
• Settings page for user preferences
• Admin panel (if ADMIN_EMAIL is set)

🛠️ Debug Panel

Visit /debug to see your configuration status:

• ✅ Convex backend connection
• ✅ Authentication setup
• ⚠️ Email provider (console mode by default)
• ⚠️ Payment providers (mock mode by default)

⚡ Next Steps (5 more minutes)

Enable Email (Optional)

Get a Resend account (free tier):

# Add to .env.local
EMAIL_PROVIDER="resend"
RESEND_API_KEY="your-resend-api-key"

Enable Payments (Optional)

Get a Stripe account (test mode):

# Add to .env.local
STRIPE_SECRET_KEY="sk_test_..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."

Set Up Admin Access

To access admin features at /admin:

# 1. Add your email to .env.local
ADMIN_EMAIL="your-email@example.com"

# 2. Sign in with that email via OAuth
# 3. Run the admin setup script
pnpm tsx scripts/fix-admin.ts

📱 Start Mobile App (Optional)

In a new terminal:

pnpm dev:mobile

Scan the QR code with:

• iOS: Camera app or Expo Go app
• Android: Expo Go app

The mobile app shares components and utilities with the web app.

🧪 Explore Features

Now that you're up and running, explore these features:

Authentication Flows

• Sign up with email/password
• OAuth sign-in (configure providers in auth settings)
• Password reset flow
• Email verification

Dashboard Features

• User profile management
• Settings and preferences
• Data visualization
• CRUD operations

Developer Features

• Hot module reloading
• TypeScript error checking
• Database schema management
• Email template preview

🎓 Learn More

Ready to dive deeper? Continue with:

1. Project Structure - Understand the codebase
2. Development Guide - Development workflow
3. Database Guide - Master the database layer
4. Authentication Guide - Secure authentication

🆘 Need Help?

If something isn't working:

1. Check the debug panel at http://localhost:3020/debug
2. Verify your NEXT_PUBLIC_CONVEX_URL is correct
3. Check the logs in your terminal for error messages
4. See Troubleshooting for common issues

🔥 Pro Tips

Speed Up Development

# Use changed-files-only commands for faster development
pnpm lint:changed          # Lint only changed files
pnpm type-check:changed     # Type-check only changed files
pnpm test:changed           # Test only changed files

Backend Management

npx convex dashboard        # Open Convex dashboard
npx convex dev              # Start Convex dev server
npx convex deploy           # Deploy to production

Code Quality

pnpm lint                   # Check code quality
pnpm type-check             # TypeScript validation
pnpm test                   # Run test suite

🎉 Congratulations!

You now have a production-ready SaaS application running with:

• ✅ Convex backend with real-time queries
• ✅ Authentication system with session management
• ✅ Responsive web app with dark mode
• ✅ Mobile app with shared code
• ✅ Development tools and hot reloading
• ✅ Type safety throughout the stack

You're ready to start building your unique features on top of this solid foundation.

Next: Dive into the Project Structure to understand how everything fits together.