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 PostgreSQL. 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 PostgreSQL database
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:

PostgreSQL-first - Unlike SQLite-based starters, it's production-ready from day one
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 database 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
PostgreSQL knowledge is helpful but not necessary
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 PostgreSQL instead of SQLite or other databases?

PostgreSQL offers significant advantages for SaaS applications:

Production scalability - Handles millions of records efficiently
Advanced features - JSON columns, full-text search, extensions
Data integrity - ACID compliance and robust transaction support
Industry standard - Widely supported by hosting platforms
Type safety - Better TypeScript integration with Drizzle ORM

Can I use a different database?

While Solo Kit is optimized for PostgreSQL, Drizzle ORM supports other databases:

MySQL - Possible with minimal configuration changes
SQLite - Suitable for prototyping but not recommended for production
PlanetScale - Compatible with PostgreSQL configuration

However, some features may require PostgreSQL-specific functionality.

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 databases - Add 2-3 weeks for database concepts

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 (PostgreSQL architecture)
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
Database studio - Visual database 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:

Database changes - Create migration with Drizzle
API routes - Add server actions or API routes
UI components - Use shadcn/ui components
State management - Use React Query for server state
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 built-in PostgreSQL

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 - Use production PostgreSQL (Neon, Supabase, Railway)
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 database migrations in production?

Solo Kit provides safe migration strategies:

Automated migrations - Run migrations during deployment
Manual migrations - Review and run migrations manually
Rolling deployments - Zero-downtime migration strategies
Backup strategies - Automatic backups before migrations

What about scaling?

Solo Kit is built for scale:

Stateless architecture - Easy horizontal scaling
Database optimization - Efficient queries with Drizzle ORM
CDN support - Static assets served from CDN
Edge functions - Reduced latency with edge computing
Caching layers - React Query and Next.js caching

🛠️ 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
Database connection - Verify DATABASE_URL is correct
Port conflicts - Check if port 3000 is available

Database connection fails

Check these common issues:

DATABASE_URL format - Ensure proper PostgreSQL URL format
Network access - Verify database allows connections from your IP
Credentials - Check username, password, and database name
SSL requirements - Some providers require SSL connections
Firewall - Check local firewall settings

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
SQL injection prevention - Drizzle ORM prevents SQL injection
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