FAQ

Frequently Asked Questions

Get quick answers to the most common questions about Solo Kit.

Solo Kit is a modern, production-ready SaaS starter kit built with React, Next.js, and Convex. It provides a complete foundation for building scalable web and mobile applications with shared code, built-in authentication, payments, email system, and more.

Why should I use Solo Kit instead of starting from scratch?

Solo Kit saves you months of development time by providing:

Production-ready architecture with Convex backend
Built-in authentication with session management
Payment processing with multiple providers
Email system with React Email templates
Mobile app with shared code between web and mobile
Type safety throughout the entire stack
Modern development tools and best practices

How is Solo Kit different from other starters?

Solo Kit is unique because it's:

Real-time first - Built on Convex for automatic real-time updates
Cross-platform - Shared code between web and mobile applications
Feature flag driven - Enable services incrementally as you need them
Type-safe end-to-end - Full TypeScript coverage from backend to UI
Session-based auth - More secure than JWT-only authentication
Comprehensive - Includes everything you need for a modern SaaS

Do I need to know all the technologies in the stack?

No! Solo Kit is designed to be approachable for developers with different experience levels:

React knowledge is the main requirement
TypeScript helps but isn't required initially
Convex is easy to learn with excellent documentation
Next.js patterns are well-documented and straightforward

You can learn these technologies as you go, and the comprehensive documentation helps guide you.

🏗️ Architecture & Setup

Why Convex instead of a traditional database?

Convex offers significant advantages for SaaS applications:

Real-time by default - Automatic real-time updates across all clients
Production scalability - Automatic scaling with no configuration
Type safety - Full TypeScript integration from backend to UI
Serverless functions - Write backend logic as TypeScript functions
ACID transactions - Built-in transactional guarantees

Can I use a different database?

Solo Kit is optimized for Convex, which provides:

Integrated backend - Database, functions, and real-time sync in one
No infrastructure management - Fully managed service
Automatic migrations - Schema changes handled automatically

If you need a traditional SQL database, you could adapt the codebase, but you'd lose the real-time and serverless benefits.

What's the learning curve like?

The learning curve depends on your background:

Experienced React developers - 1-2 weeks to feel comfortable
New to TypeScript - Add 1-2 weeks for TypeScript concepts
New to Next.js - Add 1 week for App Router patterns
New to Convex - Just 1-2 days thanks to excellent documentation

The comprehensive documentation and examples help accelerate learning.

Can I remove features I don't need?

Absolutely! Solo Kit uses feature flags to enable/disable functionality:

Database - Always required (Convex backend)
Authentication - Can be customized or simplified
Email system - Can be disabled or use console logging
Payments - Can be disabled entirely
Mobile app - Can be removed if not needed
Internationalization - Optional, can be removed

💻 Development

What's the development workflow like?

Solo Kit provides an excellent development experience:

Hot reloading - Changes appear instantly in browser
Type checking - Real-time TypeScript error checking
Convex dashboard - Visual database and function management
Email preview - Preview emails in development
Debug panel - Visual feature flag status at /debug

How do I add new features?

Follow the established patterns:

Backend changes - Add queries/mutations in Convex
API routes - Add server actions or API routes
UI components - Use shadcn/ui components
State management - Use Convex's real-time hooks
Testing - Add unit and integration tests

Can I use different UI components?

Yes, while shadcn/ui is included by default, you can:

Replace shadcn/ui with other component libraries
Mix and match different component sources
Create custom components following the established patterns
Use headless libraries like Radix UI directly

How do I handle environment variables?

Solo Kit uses a three-file strategy:

.env - Safe defaults committed to git
.env.local - Sensitive values, ignored by git
.env.example - Documentation and examples

This allows immediate development while maintaining security.

What about testing?

Solo Kit includes comprehensive testing setup:

Unit tests - Vitest with React Testing Library
Integration tests - API and database testing
E2E tests - Playwright for full user flows
Type checking - TypeScript for compile-time checks
Linting - ESLint for code quality

🚀 Deployment

Where can I deploy Solo Kit?

Solo Kit works with many hosting platforms:

Recommended:

Vercel - Zero-config deployment with edge functions
Railway - Simple deployment with excellent performance

Also supported:

Netlify - With adapter configuration
AWS - Using Docker containers
Google Cloud - Container deployment
DigitalOcean - App Platform or Droplets
Fly.io - Docker-based deployment

Do I need to configure anything special for production?

Solo Kit is production-ready out of the box, but you should:

Environment variables - Set production values in .env.local
Database - Convex production deployment (automatic)
Email provider - Configure Resend, SendGrid, or Postmark
Payment provider - Set up Stripe or other payment processors
Analytics - Configure Sentry or other monitoring tools

How do I handle schema changes in production?

Convex provides safe schema evolution:

Automatic handling - Schema changes are applied automatically
Zero downtime - No migration scripts needed
Type safety - TypeScript catches schema mismatches at build time
Rollback support - Easy to revert changes if needed

What about scaling?

Solo Kit is built for scale:

Automatic scaling - Convex handles scaling automatically
Real-time sync - Efficient data synchronization across clients
CDN support - Static assets served from CDN
Edge functions - Reduced latency with edge computing
Built-in caching - Convex's reactive caching layer

🛠️ Troubleshooting

The app won't start - what should I check?

Common issues and solutions:

Node.js version - Ensure Node.js 18+ is installed
Dependencies - Run pnpm install to install dependencies
Environment variables - Check .env.local for required variables
Convex setup - Verify NEXT_PUBLIC_CONVEX_URL is correct
Port conflicts - Check if port 3000 is available

Convex connection fails

Check these common issues:

NEXT_PUBLIC_CONVEX_URL - Ensure Convex URL is set correctly
Convex dev server - Run npx convex dev to start the backend
Authentication - Ensure you're logged into Convex CLI
Project setup - Run npx convex init if starting fresh
Network access - Check your internet connection

Build fails with TypeScript errors

TypeScript build issues:

Run type check - pnpm type-check to see specific errors
Update dependencies - Ensure all packages are up to date
Check imports - Verify all imports are correct
Clear cache - Delete .next folder and rebuild
Memory issues - Increase Node.js memory limit

Mobile app won't start

Expo development issues:

Expo CLI - Ensure latest Expo CLI is installed
Dependencies - Run pnpm install in the mobile directory
Device connection - Check device/simulator is properly connected
Network - Ensure both device and computer are on same network
Cache - Clear Expo cache with expo start --clear

🔐 Security

Is Solo Kit secure by default?

Yes, Solo Kit follows security best practices:

Session-based authentication - More secure than JWT-only
CSRF protection - Built-in cross-site request forgery protection
Type-safe queries - Convex prevents injection attacks
XSS protection - React's built-in XSS protection
Security headers - Proper security headers configured
Environment variables - Secure secret management

How do I implement role-based access control?

Solo Kit provides a foundation for RBAC:

User roles - Define roles in database schema
Permission checks - Server-side permission validation
Route protection - Protect routes based on roles
UI conditionals - Show/hide features based on permissions
API protection - Validate permissions in API routes

Solo Kit includes GDPR-ready features:

Data export - Export user data functionality
Data deletion - Delete user account and data
Consent management - Cookie and data consent handling
Privacy controls - User privacy preference management
Audit logging - Track data access and modifications

💳 Payments & Billing

Which payment providers are supported?

Solo Kit supports multiple payment providers:

Stripe - Global payment processing (recommended)
PayMongo - Payment processing for Southeast Asia
Lemon Squeezy - All-in-one platform for digital products
Polar - Payment processing for developers

How do I handle subscriptions?

Solo Kit provides subscription management:

Subscription plans - Define plans in database
Webhook handling - Process payment webhooks
Plan upgrades/downgrades - Handle plan changes
Proration - Handle prorated billing
Cancellation - Manage subscription cancellations

Can I use multiple payment providers?

Yes, Solo Kit's architecture supports multiple providers:

Geographic routing - Different providers for different regions
Fallback options - Use backup providers if primary fails
A/B testing - Test different providers for conversion
Feature flags - Enable/disable providers per environment

📱 Mobile Development

Do I need React Native experience?

Basic React knowledge is sufficient:

Expo managed workflow - Simplifies React Native development
Shared components - Use web components in mobile app
Similar patterns - Same React patterns work in mobile
Hot reloading - Fast development feedback loop

Can I eject from Expo?

Yes, but consider the trade-offs:

Pros:

Access to all native modules
Custom native code
More control over build process

Cons:

More complex setup and maintenance
Need native development knowledge
Lose Expo's convenience features

How do I deploy mobile apps?

Solo Kit mobile deployment options:

Development builds - Internal testing with Expo
TestFlight/Play Console - Beta testing distribution
App Store deployment - Production app store releases
Over-the-air updates - Update JavaScript code without store approval

🆘 Getting Help

Where can I get help?

Multiple support channels available:

Documentation - Comprehensive guides and examples
GitHub Issues - Bug reports and feature requests
Community Discussions - Questions and community help
Stack Overflow - Tag questions with solo-kit
Discord - Real-time community chat

How do I report bugs?

To report bugs effectively:

Check existing issues - Search for similar problems
Minimal reproduction - Create minimal example showing the issue
Environment details - Include OS, Node.js version, package versions
Error messages - Include complete error messages and stack traces
Steps to reproduce - Clear steps to reproduce the issue

Can I get commercial support?

Commercial support options:

Priority support - Faster response times
Custom development - Feature development and customization
Training - Team training on Solo Kit development
Consulting - Architecture and development consulting
Code review - Professional code review services

How can I contribute?

Contribute to Solo Kit:

Documentation - Improve and expand documentation
Bug fixes - Fix bugs and submit pull requests
Feature development - Develop new features
Testing - Test new features and report issues
Community support - Help other developers in discussions

Still have questions?

If you can't find an answer here, don't hesitate to ask:

Open a GitHub Issue for bugs or feature requests
Start a Discussion for questions or ideas
Check the Documentation for detailed guides and examples

We're here to help you succeed with Solo Kit!

FAQ