ModernStack SaaS Starter - SvelteKit + Convex + Better Auth

A production-ready SaaS starter template built for the Modern Stack Hackathon, featuring SvelteKit, Convex, Better Auth, Autumn Stripe billing, and more.

Tech Stack

• SvelteKit with Svelte 5 - Modern, reactive frontend framework
• Convex - Real-time backend database with serverless functions
• Better Auth - Comprehensive authentication solution with email/password and OAuth
• Autumn - Stripe billing wrapper for seamless payment integration
• Resend - Transactional email service for password resets and email verification
• shadcn-svelte - Beautiful, accessible UI components
• Tailwind CSS v4 - Utility-first CSS framework
• Lucide - Beautiful icon library

Features

• ✅ Authentication System

  • Email/password authentication
  • Google OAuth support
  • Password reset flow
  • Email change with verification
  • Session management

• ✅ User Management

  • User profile settings
  • Avatar upload with Convex storage
  • Account information management

• ✅ UI Components

  • Dashboard with charts and data tables
  • Sidebar navigation
  • Settings pages (Account, Password, Email)
  • Responsive design
  • Dark/light mode ready

• ✅ Developer Experience

  • TypeScript throughout
  • Type-safe database queries
  • Hot module replacement
  • ESLint & Prettier configured
  • LLM-focused documentation in /docs + CLAUDE.md for AI-assisted development
  • GitHub Actions CI/CD for code quality checks and Cloudflare deployments

Roadmap

Planned features and improvements:

• OAuth Support - Complete social provider integration and example with Google OAuth
• Multi-tenancy / Team Support - Organizations, team invites, and role-based permissions
• GitHub Action for Cloudflare Workers - Currently, only Cloudflare Pages deployment is fully functional
• Rate Limiting - API rate limiting and request throttling
• Stripe Stats in Admin Dashboard - Revenue analytics and subscription metrics
• Welcome Email Template - Branded welcome emails for new users
• E2E Tests with Playwright - Comprehensive end-to-end testing suite

Getting Started

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm

Installation

1. Clone the repository:

git clone https://github.com/joachimchauvet/modernstack-saas
cd modernstack-saas

2. Install dependencies:

pnpm install

3. Initialize Convex:

pnpm convex dev

When you run convex dev for the first time, it will:

• Create a new Convex project (or connect to an existing one)
• Generate your Convex deployment URL
• Output your CONVEX_DEPLOYMENT and PUBLIC_CONVEX_URL values in .env.local

4. Set up environment variables:

Convex functions run in Convex's cloud environment and can't read your local .env files. You must set environment variables separately for Convex and SvelteKit.

A. Set Convex Environment Variables

After convex dev completes, set these in Convex's environment:

# Required - Better Auth needs this to set cookies correctly
npx convex env set SITE_URL http://localhost:5173

# Required - Generate a secret for Better Auth
npx convex env set BETTER_AUTH_SECRET=$(openssl rand -base64 32)

# Required if you want email functionality (password reset, email change)
npx convex env set RESEND_API_KEY your_resend_api_key
npx convex env set RESET_EMAIL_FROM "Your App <[email protected]>"

# Optional - Customize reply to address
npx convex env set RESET_EMAIL_REPLY_TO [email protected]

# Optional - Enable Google OAuth (see docs/better_auth.md for setup)
npx convex env set GOOGLE_CLIENT_ID your_google_client_id
npx convex env set GOOGLE_CLIENT_SECRET your_google_client_secret

# Optional - Enable billing with Autumn/Stripe
npx convex env set AUTUMN_SECRET_KEY your_autumn_secret_key

Verify your Convex env vars are set:

npx convex env list

After setting Convex environment variables, restart your convex dev server (pnpm convex dev).

B. Set SvelteKit Environment Variables

Update your .env.local file in the root directory:

# PUBLIC_CONVEX_URL is auto-generated by Convex
PUBLIC_CONVEX_URL=https://xxx.convex.cloud

# PUBLIC_CONVEX_SITE_URL: Convert the .convex.cloud URL to .convex.site
# Example: if PUBLIC_CONVEX_URL is https://xxx.convex.cloud,
# then PUBLIC_CONVEX_SITE_URL should be https://xxx.convex.site
PUBLIC_CONVEX_SITE_URL=https://xxx.convex.site

# This should match what you set in Convex (used by SvelteKit hooks)
SITE_URL=http://localhost:5173

5. Start the development server:

pnpm dev

The app will be running at http://localhost:5173

Development

Run both the SvelteKit dev server and Convex in parallel:

# Terminal 1 - Convex backend
pnpm convex dev

# Terminal 2 - SvelteKit frontend
pnpm dev

Project Structure

├── src/
│   ├── lib/
│   │   ├── components/     # UI components
│   │   ├── auth-client.ts  # Better Auth client
│   │   └── ...
│   ├── routes/
│   │   ├── (app)/          # Protected routes
│   │   │   ├── dashboard/
│   │   │   └── settings/
│   │   └── auth/           # Authentication routes
│   └── convex/             # Convex backend
│       ├── auth.ts         # Auth configuration
│       ├── storage.ts      # File storage
│       └── ...

Building for Production

Create a production build:

pnpm build

Preview the production build:

pnpm preview

Deployment

This starter uses adapter-cloudflare by default, but you can swap it for any SvelteKit adapter:

• Vercel
• Netlify
• Node
• Other adapters

Deployment Steps

1. Deploy your Convex backend:

pnpm convex deploy

2. Set Convex environment variables for production:

# Update SITE_URL to your production domain
npx convex env set SITE_URL https://yourdomain.com

# Set other Convex env vars if not already set
npx convex env set BETTER_AUTH_SECRET=$(openssl rand -base64 32)
npx convex env set RESEND_API_KEY your_resend_api_key
npx convex env set RESET_EMAIL_FROM "Your App <[email protected]>"
npx convex env set RESET_EMAIL_REPLY_TO [email protected]
npx convex env set GOOGLE_CLIENT_ID your_google_client_id
npx convex env set GOOGLE_CLIENT_SECRET your_google_client_secret
npx convex env set AUTUMN_SECRET_KEY your_autumn_secret_key

3. Set SvelteKit environment variables for build:

These variables use SvelteKit's $env/static/* imports, which means they're baked into the bundle at build time. Set them where your build runs, not in your hosting platform's runtime environment variables.

• PUBLIC_CONVEX_URL - Your Convex deployment URL
• PUBLIC_CONVEX_SITE_URL - Your Convex site URL
• SITE_URL - Your production domain (e.g., https://yourdomain.com)

If using GitHub Actions (like the included Cloudflare Pages workflow):

Set these as GitHub repository variables (Settings → Secrets and variables → Actions → Variables):

• PUBLIC_CONVEX_URL
• PUBLIC_CONVEX_SITE_URL
• SITE_URL

The workflow will automatically use these during the build step.

If deploying directly from your machine or other CI/CD:

Set these as environment variables when running pnpm build:

• Vercel: Project Settings → Environment Variables (make sure they're available at build time)
• Netlify: Site Settings → Environment Variables (available during build)
• Cloudflare Pages: Settings → Environment Variables (if not using GitHub Actions)
• Cloudflare Workers: wrangler secret put VARIABLE_NAME (for runtime secrets only)

4. Deploy your frontend to your chosen platform

Documentation

This project includes comprehensive documentation optimized for LLM consumption:

• /docs - Framework-specific guides and best practices
  • svelte/ - Svelte 5 runes, reactivity, templating, and state management
  • better_auth.md - Authentication setup and patterns
  • convex.md - Backend queries, mutations, and real-time data
  • tailwind_v4.md - Styling with Tailwind CSS v4
  • autumn.md - Billing and subscription management

CI/CD

GitHub Actions workflows are included for:

• Code Quality (.github/workflows/code-quality.yml) - Linting, formatting, type checking, and spell checking on every push/PR
• Cloudflare Pages (.github/workflows/cloudflare-pages.yml) - Automatic deployments with preview URLs for pull requests
• Cloudflare Workers (.github/workflows/deploy-workers.yml) - Alternative deployment target with more features

Built for Modern Stack Hackathon

This starter template was created for the Convex Modern Stack Hackathon, showcasing the power of combining modern web technologies to build production-ready SaaS applications.

🚀 Ready to Ship?

Stop plumbing, start vibing. Modern stack, zero setup headaches.

✓ Auth • ✓ Payments • ✓ Real-time DB • ✓ Your brilliant idea? Add here →

Fork & Ship on GitHub • MIT Licensed • Built for developers