Installation

Installation Guide

This comprehensive guide covers everything you need to install and configure Solo Kit for development.

📋 Prerequisites

System Requirements

Operating System:

• macOS 10.15 (Catalina) or later
• Windows 10 version 1903 or later (with WSL2 recommended)
• Linux (Ubuntu 18.04+, Debian 10+, or equivalent)

Required Software:

Node.js 18+

Solo Kit requires Node.js version 18 or higher for modern JavaScript features.

Install Node.js:

Option A: Node.js Official Installer

1. Visit nodejs.org
2. Download the LTS version (18+)
3. Run the installer and follow instructions
4. Verify installation: node --version

Option B: Node Version Manager (Recommended)

# Install nvm (macOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install latest LTS Node.js
nvm install --lts
nvm use --lts

Windows with nvm-windows:

1. Download from github.com/coreybutler/nvm-windows
2. Run installer
3. Open new terminal and run: nvm install lts && nvm use lts

Package Manager: pnpm

Solo Kit uses pnpm for fast, efficient package management.

# Install pnpm globally
npm install -g pnpm

# Verify installation
pnpm --version

Git

Required for version control and cloning the repository.

Install Git:

• macOS: xcode-select --install or download from git-scm.com
• Windows: Download from git-scm.com or use winget install Git.Git
• Linux: sudo apt install git (Ubuntu/Debian) or equivalent

Code Editor (Recommended)

While any editor works, these provide the best experience:

Visual Studio Code (Recommended)

• Download from code.visualstudio.com
• Excellent TypeScript support
• Rich extension ecosystem
• Integrated terminal

WebStorm

• Professional IDE with advanced features
• Built-in TypeScript support
• Integrated debugging tools

Cursor

• AI-powered code editor
• Built on VS Code architecture
• Excellent for modern development

🚀 Installation Steps

1. Clone the Repository

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

# Or clone using SSH (if you have SSH keys set up)
git clone git@github.com:your-username/solo-kit.git
cd solo-kit

2. Install Dependencies

Solo Kit uses a monorepo structure. One command installs everything:

# Install all dependencies for web, mobile, and shared packages
pnpm install

What this installs:

• Web app dependencies (Next.js, React, etc.)
• Mobile app dependencies (Expo, React Native, etc.)
• Shared package dependencies (UI components, utilities)
• Development tools (ESLint, Prettier, TypeScript, etc.)

Installation time: Usually 2-3 minutes depending on internet speed.

3. Environment Configuration

Solo Kit uses a three-file environment strategy:

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

Environment Files:

• .env - Safe defaults (committed to git)
• .env.local - Sensitive values (ignored by git)
• .env.example - Documentation (committed to git)

4. Convex Backend Setup

Solo Kit uses Convex for its real-time backend. Set up is simple:

Initialize Convex

# Start Convex development server (creates account if needed)
npx convex dev

This command:

1. Creates a Convex account if you don't have one
2. Sets up a new Convex project
3. Automatically adds NEXT_PUBLIC_CONVEX_URL to your .env.local
4. Syncs your schema from the convex/ directory

Expected output:

✓ Convex functions ready in 2.1s
✓ Connected to https://your-project.convex.cloud
✓ Watching for file changes...

Convex Features

Free tier includes:

• Unlimited projects
• 1GB storage
• Real-time subscriptions
• Automatic scaling
• Built-in authentication support

Access Dashboard

View your data and functions in the Convex dashboard:

npx convex dashboard

5. Verify Backend Connection

The Convex backend syncs automatically. Your schema is defined in convex/schema.ts and functions in convex/ directory.

6. Verify Installation

Start the development server to verify everything is working:

pnpm dev

Expected output:

> solo-kit@0.7.1 dev
> pnpm dev:web

> web@0.2.7 dev
> next dev --turbo

▲ Next.js 15.5.2 (Turbopack)
- Local:        http://localhost:3020
- Network:      http://192.168.1.100:3000

✓ Ready in 2.5s

Visit these URLs to verify:

• Main app: http://localhost:3020
• Debug panel: http://localhost:3020/debug

🔧 Optional Configuration

Admin Access Setup

To enable admin features and access /admin routes:

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

# 2. Start the app and sign in with that email using OAuth

# 3. Run the admin setup script
pnpm tsx scripts/fix-admin.ts

Email Provider Setup

For development: Email is logged to console by default.

For production: Configure a real email provider.

Resend (Recommended)

1. Sign up at resend.com
2. Create API key
3. Add to .env.local:

EMAIL_PROVIDER="resend"
RESEND_API_KEY="re_abc123..."

SendGrid

1. Sign up at sendgrid.com
2. Create API key
3. Add to .env.local:

EMAIL_PROVIDER="sendgrid"
SENDGRID_API_KEY="SG.abc123..."

Payment Provider Setup

For development: Payments are mocked by default.

For production: Configure payment providers.

Stripe

1. Sign up at stripe.com
2. Get test API keys from dashboard
3. Add to .env.local:

STRIPE_SECRET_KEY="sk_test_your_secret_key_here"
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_your_publishable_key_here"

PayMongo (Southeast Asia)

1. Sign up at paymongo.com
2. Get API keys
3. Add to .env.local:

PAYMONGO_SECRET_KEY="sk_test_abc123..."

OAuth Providers Setup

Configure social login providers:

GitHub OAuth

1. Go to GitHub Settings > Developer settings > OAuth Apps
2. Create new OAuth app:
   • Application name: Solo Kit Dev
   • Homepage URL: http://localhost:3020
   • Callback URL: http://localhost:3020/api/auth/callback/github
3. Add to .env.local:

GITHUB_CLIENT_ID="abc123..."
GITHUB_CLIENT_SECRET="def456..."

Google OAuth

1. Go to Google Cloud Console
2. Create new project or select existing
3. Enable Google+ API
4. Create OAuth 2.0 credentials:
   • Authorized origins: http://localhost:3020
   • Authorized redirect URIs: http://localhost:3020/api/auth/callback/google
5. Add to .env.local:

GOOGLE_CLIENT_ID="abc123...apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="def456..."

🏗️ Project Structure Verification

After installation, your project should look like this:

solo-kit/
├── apps/
│   ├── web/                 # Next.js web application
│   │   ├── app/            # App router pages
│   │   ├── components/     # React components
│   │   ├── lib/           # Utilities and configurations
│   │   └── package.json   # Web app dependencies
│   └── mobile/            # Expo mobile application
│       ├── app/           # Mobile app screens
│       ├── components/    # Mobile components
│       └── package.json   # Mobile app dependencies
├── packages/
│   ├── ui/               # Shared UI components
│   ├── utils/            # Shared utilities
│   └── eslint-config/    # Shared ESLint configuration
├── convex/               # Convex backend (schema, functions)
├── .env                  # Safe defaults (committed)
├── .env.local           # Your sensitive config (ignored)
├── .env.example         # Documentation
├── package.json         # Root package configuration
├── pnpm-workspace.yaml  # Workspace configuration
└── turbo.json          # Build system configuration

✅ Verification Checklist

Ensure everything is working correctly:

✅ Basic Functionality

• node --version shows 18+
• pnpm --version works
• pnpm dev starts without errors
• http://localhost:3020 loads the landing page
• Convex connection works (check /debug)

✅ Backend Features

• npx convex dashboard opens Convex dashboard
• Can create user account via sign-up form
• User data appears in Convex dashboard
• Authentication redirects work

✅ Development Tools

• Hot reloading works when editing files
• TypeScript errors show in terminal
• pnpm lint runs without errors
• pnpm type-check passes

✅ Optional Features (if configured)

• Email provider works (test with sign-up)
• OAuth providers work (test sign-in)
• Payment provider loads (check /debug)
• Admin access works (if ADMIN_EMAIL set)

🐛 Troubleshooting Installation

Common Issues and Solutions

Node.js Version Error

Error: This package requires Node.js version 18 or higher

Solution: Install Node.js 18+ using the methods above.

pnpm Not Found

pnpm: command not found

Solution: Install pnpm globally: npm install -g pnpm

Convex Connection Failed

Error: Could not connect to Convex

Solutions:

1. Verify NEXT_PUBLIC_CONVEX_URL is set in .env.local
2. Run npx convex dev to start the Convex dev server
3. Check your internet connection
4. Ensure you're logged into Convex CLI (npx convex login)

Port Already in Use

Error: Port 3000 is already in use

Solutions:

1. Kill process using port: lsof -ti:3000 | xargs kill
2. Use different port: PORT=3001 pnpm dev
3. Find and stop conflicting application

Permission Errors (macOS/Linux)

EACCES: permission denied

Solutions:

1. Use Node version manager instead of sudo
2. Fix npm permissions: npm config set prefix ~/.npm-global
3. Add to PATH: export PATH=~/.npm-global/bin:$PATH

Windows WSL Issues

Solutions:

1. Use WSL2 instead of WSL1
2. Install Node.js inside WSL, not Windows
3. Clone repository inside WSL filesystem

Getting Help

If you're still having issues:

1. Check the debug panel at http://localhost:3020/debug
2. Search existing issues on GitHub
3. Create new issue with:
   • Operating system and version
   • Node.js version (node --version)
   • pnpm version (pnpm --version)
   • Complete error message
   • Steps you've tried

🎉 Next Steps

Great! You now have Solo Kit fully installed and configured. Continue with:

1. Project Structure - Understand the codebase organization
2. Editor Setup - Configure your editor for the best experience
3. Development - Learn the development workflow
4. Database Guide - Master the database layer

🔄 Updating Solo Kit

To update to a newer version of Solo Kit:

# Pull latest changes
git pull origin main

# Update dependencies
pnpm install

# Sync Convex schema if needed
npx convex dev

# Check for any breaking changes in CHANGELOG.md

Always review the changelog before updating to understand any breaking changes or new features.