Technical Overview - Configuration Guide

Welcome to the technical overview of the Next.js + Convex SaaS boilerplate. This guide provides a comprehensive understanding of the technical architecture, configuration patterns, and development setup.

🚀 Complete Tech Stack

Frontend & Framework

Next.js 15 - React 19 with App Router architecture
TypeScript - Strict type safety throughout the entire application
Tailwind CSS 4 - Modern utility-first styling with PostCSS
shadcn/ui - Production-ready component library with “new-york” style
Lucide React - Modern icon library for consistent iconography
next-themes - Seamless dark/light mode switching

Backend & Database

Convex - Serverless backend with real-time database capabilities
@convex-dev/auth - Built-in authentication system with multiple providers
@convex-dev/presence - Real-time user presence tracking
@convex-dev/aggregate - Data aggregation and analytics helpers
convex-helpers - Utility functions and common patterns

Authentication & Security

OAuth Providers - Google OAuth integration (extensible for GitHub, etc.)
Password Authentication - Email/password with secure reset functionality
Email Verification - Via Resend integration with custom templates
Middleware Protection - Route-level authentication guards
Role-Based Access - Admin, member, and developer role system

Payments & Billing

Stripe Integration - Complete subscription management system
Webhook Handling - Automated billing event processing
Multiple Intervals - Monthly, yearly, and one-time payment support
Customer Portal - Self-service billing management
Price Management - Dynamic pricing through admin interface

Communication & Notifications

Resend - Reliable email delivery service
React Email - Type-safe email template system
Real-time Notifications - In-app notification center
Team Alerts - Slack/Discord integration for admin notifications

Development Tools

ESLint - Code quality and consistency enforcement
Prettier - Automated code formatting with import sorting
npm-run-all - Parallel development server execution
TypeScript Strict Mode - Maximum type safety and error prevention

🏗️ Architecture Patterns

Route Organization

The application uses Next.js App Router with route groups for logical organization:


app/
├── (authenticated)/                    # Protected routes requiring auth
│   ├── (user-app)/                    # Main user application
│   │   ├── (onboarding-required)/     # Onboarding flow protection
│   │   └── workspaces/                # Workspace management
│   └── (dev-app)/                     # Developer/admin interface
├── (public-with-convex-auth-client)/  # Public auth pages
├── (public-with-convex-client)/       # Public pages with Convex
└── (public-docs)/                     # Documentation routes

Component Architecture

Page-specific components in _components/ directories
Shared components in /components/ with ui/ subdirectory
Custom hooks in _hooks/ using the pattern use<Feature>.<Operation>.tsx
shadcn/ui integration with customizable base components

Backend Organization


convex/
├── core/                     # Core business domain functions
│   ├── *.queries.ts         # Read operations with subscriptions
│   ├── *.mutations.ts       # Write operations and data modification
│   ├── *.validators.ts      # Input validation and type safety
│   └── *.helpers.ts         # Shared utility functions
├── schema/                   # Database schema definitions
│   ├── core.ts              # Core tables (users, workspaces, etc.)
│   └── feat.ts              # Feature-specific tables
├── _generated/               # Auto-generated Convex types
└── auth.ts                   # Authentication configuration

⚙️ Configuration Files

Core Configuration

package.json


{
  "scripts": {
    "dev": "npm-run-all --parallel dev:frontend dev:backend",
    "dev:frontend": "next dev --turbopack",
    "dev:backend": "convex dev"
  }
}

Parallel development - Frontend and backend run simultaneously
Turbopack - Enhanced Next.js development performance
Modern dependencies - Latest stable versions of all packages

next.config.ts


const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'judicious-aardvark-200.convex.cloud',
      },
    ],
  },
};

Image optimization - Configured for Convex file storage
Remote patterns - Secure image loading from Convex CDN

TypeScript Configuration


{
  "compilerOptions": {
    "strict": true,
    "target": "ES2017",
    "moduleResolution": "bundler",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Strict mode - Maximum type safety enforcement
Path aliases - Clean imports using @/ prefix
Modern target - ES2017 for optimal performance

Styling Configuration

Tailwind CSS 4 Setup

PostCSS integration via @tailwindcss/postcss
CSS variables for theme system with dark/light mode
Component styles in app/globals.css
shadcn/ui configuration in components.json

Component Library Configuration


{
  "style": "new-york",
  "rsc": true,
  "tailwind": {
    "baseColor": "neutral",
    "cssVariables": true
  },
  "iconLibrary": "lucide"
}

Database Schema

The Convex schema follows a modular pattern:


// convex/schema.ts
const schema = defineSchema({
  ...authTables,        # Convex Auth tables
  ...coreSchema,        # Core business tables
  ...featureSchema,     # Feature-specific tables
});

Core Tables Include:

users - User profiles with developer role support
workspaces - Multi-tenant workspace architecture
workspaceMembers - Role-based member management
workspaceSubscription - Stripe billing integration
workspaceNotifications - Real-time notification system

🔐 Environment Variables

Required Environment Variables


# Convex Core
CONVEX_SITE_URL=              # Generated by Convex
SITE_URL=                     # Frontend URL (set by auth setup)
 
# Authentication
AUTH_RESEND_KEY=              # Resend API key for emails
EMAIL_DOMAIN=                 # Your email domain (e.g., @mysite.com)
AUTH_GOOGLE_CLIENT_ID=        # Google OAuth client ID
AUTH_GOOGLE_CLIENT_SECRET=    # Google OAuth client secret
 
# Billing
STRIPE_SECRET_KEY=            # Stripe secret key
STRIPE_WEBHOOK_SECRET=        # Stripe webhook endpoint secret
 
# Developer Access
DEVELOPER_ROLE_PASSKEY=       # Passkey for developer role access
 
# Team Notifications (Optional)
SLACK_BOT_TOKEN=              # Slack bot token
DISCORD_BOT_TOKEN=            # Discord bot token

Environment Setup Process

Initial Setup - npx convex dev creates basic configuration
Auth Configuration - npx @convex-dev/auth sets up authentication
Manual Configuration - Set remaining environment variables
Development Start - pnpm dev launches both frontend and backend

🛠️ Development Workflow

Development Commands


# Install dependencies
pnpm install
 
# Initialize Convex backend
npx convex dev
 
# Setup authentication
npx @convex-dev/auth
 
# Start development servers
pnpm dev

Code Quality Tools

ESLint Configuration

TypeScript integration with unused variable warnings
React hooks validation for proper usage
Next.js core web vitals and best practices
JSX validation with entity escaping

Custom Development Patterns

Custom hooks pattern: use<Feature>.<Operation>.tsx
Component composition for reusable UI elements
Type-safe API with auto-generated Convex types
Workspace-scoped queries and mutations

File Organization Conventions

PascalCase for React components
kebab-case for utility files
Dot notation for Convex functions (e.g., users.queries.ts)
Route groups with parentheses for logical organization

🔧 Authentication System

Provider Configuration


// convex/auth.ts
export const { auth, signIn, signOut } = convexAuth({
  providers: [
    Password({ reset: ResendOTPPasswordReset }),
    Google({
      clientId: AUTH_GOOGLE_CLIENT_ID,
      clientSecret: AUTH_GOOGLE_CLIENT_SECRET,
    }),
  ],
});

Middleware Protection


// middleware.ts
export default convexAuthNextjsMiddleware(async (request, { convexAuth }) => {
  // Automatic redirects for authenticated users
  // Route protection for sensitive areas
});

📊 Real-time Features

Convex Real-time Capabilities

Live queries - Automatic UI updates when data changes
Presence system - Real-time user activity tracking
File storage - Integrated CDN with upload progress
Search indexing - Full-text search across content

Performance Optimizations

Server components - Optimal initial page loads
Code splitting - Automatic bundle optimization
Image optimization - Next.js Image with Convex storage
Caching strategies - Query result caching and invalidation

🚀 Deployment Ready

Production Considerations

Environment separation - Development vs. production configs
Type safety - Complete type coverage prevents runtime errors
Security - Authentication middleware and input validation
Scalability - Serverless architecture with automatic scaling
Monitoring - Built-in logging and error tracking

Deployment Platforms

Vercel - Optimal for Next.js applications
Netlify - Alternative deployment platform
Docker - Containerized deployment option
Convex - Automatic backend deployment and scaling

Next Steps

Database Setup - Configure your Convex backend schema
App Settings - Customize Next.js frontend configuration
File Storage - Setup Convex file storage for uploads
Authentication - Configure OAuth providers and email templates
Environment Variables - Set up all required environment variables
Deployment - Deploy to your preferred hosting platform

This technical foundation provides everything needed to build, scale, and maintain a modern SaaS application with confidence.