Tanvex

SaaS starter with TanStack Start + Convex real-time backend, Better Auth, Autumn billing, and Sentry monitoring.

Tech Stack

Frontend:

• React 19 - UI library with concurrent features
• TanStack Start - Full-stack React framework with SSR
• TanStack Router - Type-safe file-based routing
• TanStack Query - Server state management
• Tailwind CSS 4 - Utility-first styling
• Radix UI - Accessible component primitives
• shadcn/ui - Beautiful components built on Radix

Backend:

• Convex - Real-time serverless backend with database
• Better Auth - Type-safe authentication
• Autumn - Stripe billing integration

Monitoring:

• Sentry - Error tracking and performance monitoring

Deployment:

• Netlify - Edge hosting with auto-deploys

Developer Experience:

• TypeScript - Type safety
• Vite - Lightning-fast build tool
• Bun - Fast all-in-one runtime
• Vitest - Unit testing
• Prettier + ESLint - Code quality

---

Quick Start

Prerequisites

• Bun installed
• Convex account (free tier available)
• Autumn account for Stripe integration

1. Install HTTPS Certificates

Warning

Better Auth requires HTTPS in development.

brew install mkcert && mkcert -install
mkdir certificates
mkcert -key-file certificates/localhost-key.pem -cert-file certificates/localhost.pem localhost 127.0.0.1 ::1

See docs/SETUP.md for Linux/Windows instructions.

2. Install and Configure

# Clone and install
git clone https://github.com/RMNCLDYO/tanvex.git
cd tanvex
bun install

# Start Convex (auto-fills .env.local)
bunx convex dev

3. Set Environment Variables

In Convex Dashboard → Settings → Environment Variables:

# Required
BETTER_AUTH_SECRET=<openssl rand -base64 32>
AUTUMN_SECRET_KEY=<from https://app.useautumn.com>
VITE_DEV_SITE_URL=https://localhost:3000

See docs/ENVIRONMENT.md for complete variable reference.

4. Start Development

bun run dev  # Opens https://localhost:3000

Optional integrations: GitHub OAuth, CodeRabbit AI reports, Sentry monitoring - see docs/INTEGRATIONS.md

---

Features

• Authentication - Email/password with optional GitHub OAuth
• Billing - Multi-tier subscriptions (Free/Starter/Pro) with Stripe
• Real-time DB - Live data sync via Convex WebSocket
• Dark Mode - System preference detection + localStorage persistence
• Type Safety - End-to-end TypeScript with Zod validation
• Error Tracking - Sentry integration with correlation IDs
• Responsive UI - Mobile-first design with Tailwind
• AI Reports - CodeRabbit code review summaries (optional)

---

Architecture

graph TB
    Browser[Browser]
    Netlify[Netlify Edge]
    Start[TanStack Start SSR]
    Convex[Convex Cloud]

    Browser --> Netlify
    Netlify --> Start
    Start --> Convex
    Convex --> Auth[Better Auth]
    Convex --> Billing[Autumn/Stripe]
    Convex --> Monitoring[Sentry]

Loading

Key flows:

Authentication

sequenceDiagram
    User->>API: Credentials
    API->>Better Auth: Validate
    Better Auth->>User: Session cookie
    User->>Convex: Request + cookie
    Convex->>Frontend: Authenticated

Loading

Billing

flowchart LR
    User-->Checkout{New?}
    Checkout-->|Yes|URL[Stripe URL]
    Checkout-->|No|Modal[Inline modal]
    URL-->Stripe
    Modal-->Stripe
    Stripe-->Webhook[Convex webhook]

Loading

---

Development

bun run dev          # Dev server (https://localhost:3000)
bun run build        # Production build
bun run typecheck    # Type checking
bun run lint         # Lint code
bun run format       # Format code
bun run check        # Lint + format + typecheck
bun run test         # Run tests

Deploy to Netlify:

bunx convex deploy   # Deploy backend to Convex
git push origin main # Deploy frontend to Netlify (auto-deploys on push)

See docs/SETUP.md for complete production deployment guide.

---

Documentation

• Setup Guide - Detailed installation and configuration
• Environment Variables - All env vars explained (dev vs prod)
• Integrations - GitHub OAuth, CodeRabbit, Sentry setup
• Security - CORS, rate limiting, session handling
• Monitoring - Sentry config, logging, performance
• Troubleshooting - Common problems and solutions

---

Common Issues

Problem	Solution
Convex deployment not found	Run bunx convex dev to initialize
Better Auth errors	Verify BETTER_AUTH_SECRET in Convex Dashboard
GitHub OAuth fails	Optional feature - set DEV_GITHUB_CLIENT_ID if needed
HTTPS certificate errors	Run mkcert -install and regenerate certificates

Full troubleshooting: docs/TROUBLESHOOTING.md

---

Project Structure

tanvex/
├── app/
│   ├── routes/          # File-based routing
│   ├── components/      # React components
│   └── lib/             # Client utilities
├── convex/
│   ├── schema.ts        # Database schema
│   ├── auth.config.ts   # Better Auth config
│   ├── autumn.ts        # Billing integration
│   └── lib/             # Server utilities
├── docs/                # Documentation
└── public/              # Static assets

---

Contributing

Contributions welcome! Please open an issue first to discuss changes.

---

License

MIT © RMNCLDYO

---

Acknowledgments

Built with amazing open-source tools:

• TanStack - Tanner Linsley
• Convex - Convex team
• Better Auth - Better Auth team
• Autumn - Autumn team