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 Database

Get a free PostgreSQL database from one of these providers:

Option A: Neon (Recommended)

1. Go to neon.tech and create a free account
2. Create a new project
3. Copy the connection string

Option B: Supabase

1. Go to supabase.com and create a free account
2. Create a new project
3. Go to Settings > Database and copy the connection string

Option C: Railway

1. Go to railway.app and create a free account
2. Create a new PostgreSQL database
3. Copy the connection string

⚙️ 3. Configure Environment

Create your environment file:

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

Add your database URL to .env.local:

# Required - Your PostgreSQL database URL
DATABASE_URL="postgresql://username:password@host:port/database"

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

🏗️ 4. Initialize Database

Push the database schema to your PostgreSQL database:

pnpm db:push

This creates all necessary tables in your database.

🎉 5. Start Development

pnpm dev

Your app is now running at:

• Web App: http://localhost:3000
• Debug Panel: http://localhost:3000/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:

• ✅ Database 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:3000/debug
2. Verify your DATABASE_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

Database Management

pnpm db:studio              # Visual database browser
pnpm db:seed                # Add sample data
pnpm db:reset               # Reset database (careful!)

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:

• ✅ PostgreSQL database with type-safe 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.