🚀 TanStack Start + Better Auth

A modern authentication starter built with TanStack Start and Better Auth. Features email/password authentication with email verification and Google OAuth integration.

✨ Features

• 🔐 Multiple Authentication Methods
  • Email/password with email verification
  • Google OAuth integration
• 📧 Email Verification via Mailjet
• 🗃️ Database Ready with Docker Compose
• 🛡️ Protected Routes

🛠️ Quick Start

Prerequisites

• Node.js (v18 or higher)
• pnpm
• Docker & Docker Compose

1. Clone and Install

git clone git@github.com:janwolfram/start-better-auth.git start-better-auth
cd start-better-auth
pnpm install

2. Environment Setup

Create a .env file in the root directory:

# Database
DATABASE_URL="postgresql://postgres:example@localhost:5432/postgres"

# Better Auth
BETTER_AUTH_SECRET="your-super-secret-key-here"
BETTER_AUTH_URL="http://localhost:3000"

# Email Verification (Mailjet)
MAILJET_API_KEY="your-mailjet-api-key"
MAILJET_SECRET_KEY="your-mailjet-secret-key"
MAILJET_FROM_EMAIL="noreply@yourdomain.com"

# Google OAuth
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

3. Start the Database

pnpm db:start

This will start the PostgreSQL database container in the background.

4. Setup Database Schema

pnpm db:push

This command pushes the database schema to your running database.

5. Start Development Server

pnpm dev

Your application will be available at http://localhost:3000

🗺️ Available Routes

Route	Description	Access
/	Index page	Public
/sign-in	Sign in form	Public
/sign-up	Sign up form	Public
/protected	Protected content	Authenticated only

🔧 Configuration

Email Verification Setup

1. Create a Mailjet account
2. Get your API key and secret from the Mailjet dashboard
3. Add the credentials to your .env file
4. Configure your sender email address

Google OAuth Setup

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Create OAuth 2.0 credentials
4. Add your client ID and secret to .env
5. Configure authorized redirect URIs:
   • http://localhost:3000/api/auth/callback/google (development)
   • https://yourdomain.com/api/auth/callback/google (production)

📁 Project Structure

├── src/
│   ├── routes/              # TanStack Start routes
|   |   ├── __dashboard/
|   |   |   ├── index.tsx    # Index page
|   |   |   └── protected.tsx # Protected route
|   |   ├── __auth/
|   |   |   ├── sign-in.tsx  # Sign in page
|   |   |   └── sign-up.tsx  # Sign up page
│   ├── lib/
|   |   ├── better-auth/
|   |   |   ├── auth.ts      # Better Auth configuration
|   |   └── ...
├── docker-compose.yml       # Database container setup
├── package.json
└── README.md

🚀 Deployment

Environment Variables for Production

Make sure to update these environment variables for production:

BETTER_AUTH_URL="https://yourdomain.com"
DATABASE_URL="your-production-database-url"

Database Migration

For production deployments, ensure your database schema is up to date:

pnpm db:push

or run the migration scripts.

🛡️ Security Features

• Email Verification: Prevents registration with invalid email addresses
• Secure Sessions: Better Auth handles secure session management
• Protected Routes: Automatic redirection for unauthenticated users
• OAuth Integration: Secure Google authentication flow

🔍 Development Commands

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Start database
pnpm db:start

# Stop database
pnpm db:stop

# Push database schema
pnpm db:push

# Build for production
pnpm build

# Start production server
pnpm start

# Generate migration
pnpm db:generate

# Migrate migration
pnpm db:migrate

# Delete database
pnpm db:clear

# Reset database
pnpm db:reset

# Open drizzle studio
pnpm db:studio

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b new-feature)
3. Commit your changes (git commit -m 'Add some stuff')
4. Push to the branch (git push origin new-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• TanStack Start - Modern full-stack React framework
• Better Auth - Comprehensive authentication library
• Mailjet - Email delivery service

---