Getting Started with SaaS Core

Welcome to SaaS Core! This guide will help you set up and start using our comprehensive SaaS platform for your business needs.

🚀 Quick Start

If you're eager to get started quickly, follow these essential steps:

Clone the repository and install dependencies
Set up environment variables in .env.local
Configure your database and run migrations
Start the development server and explore the dashboard

For detailed configuration of specific services, refer to our configuration documentation.

Prerequisites

Before you begin, ensure you have the following installed:

System Requirements

Node.js 18 or later
pnpm package manager
PostgreSQL database (we recommend Neon for development)

Optional Services (Recommended)

Google Cloud Console account for OAuth
GitHub Developer account for OAuth
Resend account for email services
Stripe account for payment processing

Installation

1. Clone the Repository

git clone <your-repo-url> saas-core
cd saas-core

2. Install Dependencies

pnpm install

3. Set Up Environment Variables

Create a .env or .env.local file in the root directory:

# ===========================================
# Database Configuration
# ===========================================
DATABASE_URL="postgresql://username:password@localhost:5432/saas_core"

# ===========================================
# Authentication Configuration
# ===========================================
BETTER_AUTH_SECRET="your-super-secret-key-here-make-it-long-and-random"
BETTER_AUTH_URL="http://localhost:3000"

# ===========================================
# Email Service Configuration
# ===========================================
RESEND_API_KEY="re_xxxxxxxxxxxxxxxxxxxxxxxxxx"
EMAIL_FROM="[email protected]"
REPLY_TO_EMAIL_ADDRESSES="[email protected]"

# ===========================================
# Payment Configuration (Stripe)
# ===========================================
STRIPE_SECRET_KEY="sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxx"
STRIPE_PUBLISHABLE_KEY="pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxx"
STRIPE_WEBHOOK_SECRET="whsec_xxxxxxxxxxxxxxxxxxxxxxxxxx"

# Stripe Product Price IDs
STRIPE_SUBSCRIPTION_BASIC_PRICE_ID="price_xxxxxxxxxxxxxxxxxx"
STRIPE_SUBSCRIPTION_PRO_PRICE_ID="price_xxxxxxxxxxxxxxxxxx"

# ===========================================
# OAuth Configuration
# ===========================================
# Google OAuth
GOOGLE_CLIENT_ID="123456789012-abcdefghijklmnopqrstuvwxyz123456.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="GOCSPX-abcdefghijklmnopqrstuvwxyz123456"

# GitHub OAuth
GITHUB_CLIENT_ID="abcdef1234567890abcd"
GITHUB_CLIENT_SECRET="abcdef1234567890abcdef1234567890abcdef12"

# ===========================================
# Application Configuration
# ===========================================
NEXT_PUBLIC_APP_URL="http://localhost:3000"

Note: For detailed configuration guides for each service, refer to our configuration documents.

Database Configuration

1. Generate Authentication Schema

npx @better-auth/cli generate

Copy the generated auth schema content to your Drizzle schema in src/db/schema.ts.

2. Generate and Push Database Schema

# Generate Drizzle schema files
pnpm run db:generate

# Push schema changes to your database
pnpm run db:push

3. Verify Database Connection

You can open Drizzle Studio to verify your database setup:

pnpm run db:studio

Development

Start Development Server

pnpm run dev

Visit http://localhost:3000 to see your application running.

Available Development Commands

# Build the application
pnpm run build

# Start production server
pnpm run start

# Run ESLint
pnpm run lint

# Database operations
pnpm run db:generate    # Generate Drizzle schema files
pnpm run db:push        # Push schema changes
pnpm run db:studio      # Open Drizzle Studio
pnpm run db:migrate     # Run migrations

First Steps

Once your application is running, here's what to do next:

1. Create Your Account

Sign Up: Create a new account using email authentication
Social Login: Use Google or GitHub OAuth (if configured)
Magic Link: Receive email magic links for passwordless login

2. Explore the Dashboard

Multi-tier Access: Experience role-based dashboard views (super, admin, user)
Navigation: Familiarize yourself with the sidebar navigation
Settings: Configure your profile and preferences

3. Key Features to Explore

User Management: Manage team members and permissions
Subscription Management: Handle billing and subscription tiers
Usage Tracking: Monitor resource consumption and limits
Security Dashboard: View login activity and security settings
Newsletter System: Manage email subscribers and campaigns

4. Administrator Features

If you have admin privileges:

Access the admin dashboard
Manage all users and organizations
Configure system-wide settings
Monitor application analytics

Project Structure

Understanding the project structure will help you navigate and customize the application:

src/
├── app/                 # Next.js App Router pages
│   ├── api/            # API routes
│   ├── dashboard/      # Dashboard pages
│   └── auth/           # Authentication pages
├── components/         # React components
│   ├── dashboard/      # Dashboard-specific components
│   ├── ui/             # Reusable UI components
│   └── ... /           # Other components
├── lib/                # Utility functions and configurations
│   ├── auth.ts         # Sever side Authentication configuration
│   ├── db.ts           # Database connection
│   └── utils.ts        # Utility functions
├── db/                 # Database schema and connection
│   ├── schema.ts       # Drizzle schema definitions
│   └── index.ts        # Database connection
├── hooks/              # Custom React hooks
└── server/             # Server-side utilities

Next Steps

Explore Detailed Documentation

Components Documentation - Learn about available UI components
API Reference - Understand the API endpoints and usage
Configuration Guides - Detailed setup for each service
Deployment Guide - Production deployment instructions

Configure Additional Services

Email Service - Set up Resend for transactional emails
Payment System - Configure Stripe for subscriptions
OAuth Providers - Add Google and GitHub authentication
Database Setup - Advanced database configuration

Advanced Features

Newsletter Management - Manage email campaigns
User Management - Advanced user administration
Billing System - Subscription and payment management

Troubleshooting

Debug Mode

Enable debug mode for detailed logging:

NODE_ENV=development

Getting Help

If you encounter issues:

Check the logs for detailed error messages
Verify environment variables are correctly set
Test individual services using our configuration guides
Review the detailed documentation for each service

🎯 Ready to Go!

Congratulations! You've successfully set up SaaS Core. You now have access to:

✅ Complete user authentication system
✅ Multi-tier dashboard with role-based access
✅ Subscription and billing management
✅ Email services and newsletter system
✅ Third-party OAuth integration
✅ Comprehensive user management
✅ Security monitoring and activity tracking

Start exploring the dashboard and customizing the platform for your specific business needs. For advanced customization and deployment, refer to our detailed documentation.

Happy building! 🚀