feat: add email templates and email OTP login flow (#2110)

Author: koistya

.env

@@ -52,10 +52,10 @@ CLOUDFLARE_API_TOKEN=
 # https://firebase.google.com/docs/analytics/get-started?platform=web
 GA_MEASUREMENT_ID=G-XXXXXXXX
 
-# SendGrid
-# https://app.sendgrid.com/settings/api_keys
-SENDGRID_API_KEY=xxxxx
-FROM_EMAIL=hello@example.com
+# Resend
+# https://resend.com/api-keys
+RESEND_API_KEY=xxxxx
+RESEND_EMAIL_FROM=onboarding@resend.dev
 
 # Algolia Search
 # https://dashboard.algolia.com/account/api-keys/all

.github/workflows/main.yml

@@ -48,6 +48,7 @@ jobs:
         if: ${{ github.event_name == 'pull_request' }}
 
       # Type checking
+      - run: bun email:build # Build email templates first
       - run: bun tsc --build
 
       # Testing (commented out - enable as needed)

.gitignore

@@ -68,6 +68,10 @@ terraform.rc
 docs/.vitepress/cache
 docs/.vitepress/dist
 
+# React Email
+# Generated preview build and runtime files
+.react-email/
+
 # Local development files
 *.local.md
 *.local.json

.vscode/settings.json

@@ -55,6 +55,7 @@
   },
   "cSpell.ignoreWords": [
     "browserslist",
+    "bunx",
     "cloudfunctions",
     "corejs",
     "corepack",
@@ -89,7 +90,6 @@
     "refetch",
     "refetchable",
     "relyingparty",
-    "sendgrid",
     "signup",
     "sourcemap",
     "spdx",

CLAUDE.md

@@ -7,6 +7,7 @@ Full-stack React application template optimized for Cloudflare Workers deploymen
 - `apps/web/` - Marketing static website
 - `apps/app/` - Main application SPA
 - `apps/api/` - tRPC API server
+- `apps/email/` - React Email templates for authentication emails
 - `packages/core/` - Shared core utilities and WebSocket functionality
 - `packages/ui/` - Shared UI components and shadcn/ui management scripts
 - `db/` - Drizzle ORM schemas and migrations
@@ -50,6 +51,11 @@ bun ui:list                    # List installed components
 bun ui:update                  # Update all components
 bun ui:essentials              # Install essential components
 
+# Email Templates
+bun email:dev                  # Start email preview server
+bun email:build                # Build email templates
+bun email:export               # Export static email templates
+
 # Other
 bun lint                       # Lint all code
 bun --filter @repo/db push     # Apply DB schema changes
@@ -60,9 +66,15 @@ bun --filter @repo/db studio   # Open DB GUI
 bun --filter @repo/db seed     # Seed sample data
 
 # Deployment
-bun wrangler deploy --config apps/web/wrangler.jsonc --env=production
-bun wrangler deploy --config apps/app/wrangler.jsonc --env=production
-bun wrangler deploy --config apps/api/wrangler.jsonc --env=production
+# Build required packages first
+bun email:build                # Build email templates
+bun web:build                  # Build marketing site
+bun app:build                  # Build main React app
+
+# Deploy all applications
+bun web:deploy                 # Deploy marketing site
+bun api:deploy                 # Deploy API server
+bun app:deploy                 # Deploy main React app
 ```
 
 ## Code Conventions

README.md

@@ -32,6 +32,7 @@ This starter kit uses a thoughtfully organized monorepo structure that promotes
 - [`apps/app/`](./apps/app) — React 19 application with TanStack Router, Jotai, and Tailwind CSS v4
 - [`apps/web/`](./apps/web) — Astro marketing website for static site generation
 - [`apps/api/`](./apps/api) — tRPC API server powered by Hono framework for Cloudflare Workers
+- [`apps/email/`](./apps/email) — React Email templates for authentication and transactional emails
 - [`packages/core/`](./packages/core) — Shared TypeScript types and utilities
 - [`packages/ui/`](./packages/ui) — Shared UI components with shadcn/ui management utilities
 - [`packages/ws-protocol/`](./packages/ws-protocol) — WebSocket protocol template with type-safe messaging
@@ -112,7 +113,7 @@ bun install
 
 ### 3. Configure Environment
 
-Update environment variables in [`.env`](./.env) and `.env.local` files as well as Wrangler configuration in [`wrangler.jsonc`](./apps/edge/wrangler.jsonc).
+Update environment variables in [`.env`](./.env) and `.env.local` files as well as Wrangler configuration in [`wrangler.jsonc`](./apps/api/wrangler.jsonc).
 
 ### 4. Start Development
 
@@ -124,11 +125,10 @@ Open two terminals and run these commands:
 bun --filter @repo/app dev
 ```
 
-**Terminal 2 - Backend:**
+**Terminal 2 - API Server:**
 
 ```bash
-bun --filter @repo/edge build --watch
-bun wrangler dev
+bun --filter @repo/api dev
 ```
 
 For the marketing website:
@@ -162,13 +162,15 @@ bun wrangler secret put OPENAI_API_KEY --env=production
 ### 2. Build and Deploy
 
 ```bash
-# Build all packages
-bun --filter @repo/app build
-bun --filter @repo/web build
-bun --filter @repo/edge build
-
-# Deploy to Cloudflare Workers
-bun wrangler deploy --env=production
+# Build packages that require compilation (order matters!)
+bun email:build    # Build email templates first
+bun web:build      # Build marketing site
+bun app:build      # Build main React app
+
+# Deploy all applications
+bun web:deploy     # Deploy marketing site
+bun api:deploy     # Deploy API server
+bun app:deploy     # Deploy main React app
 ```
 
 Your application will be live on your Cloudflare Workers domain within seconds. The edge-first architecture ensures optimal performance regardless of user location.

apps/api/dev.ts

@@ -61,19 +61,21 @@ app.use("*", async (c, next) => {
     "GOOGLE_CLIENT_ID",
     "GOOGLE_CLIENT_SECRET",
     "OPENAI_API_KEY",
+    "RESEND_API_KEY",
+    "RESEND_EMAIL_FROM",
   ] as const;
 
   const env = {
     ...cf.env,
     ...Object.fromEntries(
-      secretKeys.map((key) => [key, (cf.env[key] || process.env[key]) ?? ""]),
+      secretKeys.map((key) => [key, (process.env[key] || cf.env[key]) ?? ""]),
     ),
-    APP_NAME: cf.env.APP_NAME || process.env.APP_NAME || "Example",
+    APP_NAME: process.env.APP_NAME || cf.env.APP_NAME || "Example",
     APP_ORIGIN:
       // Prefer origin set by `apps/app` at runtime
       c.req.header("x-forwarded-origin") ||
-      c.env.APP_ORIGIN ||
       process.env.APP_ORIGIN ||
+      c.env.APP_ORIGIN ||
       "http://localhost:5173",
   };
 

apps/api/lib/auth.ts

@@ -6,7 +6,9 @@ import { betterAuth } from "better-auth";
 import type { DB } from "better-auth/adapters/drizzle";
 import { drizzleAdapter } from "better-auth/adapters/drizzle";
 import { anonymous, organization } from "better-auth/plugins";
+import { emailOTP } from "better-auth/plugins/email-otp";
 import { passkey } from "better-auth/plugins/passkey";
+import { sendOTP, sendPasswordReset, sendVerificationEmail } from "./email";
 import type { Env } from "./env";
 
 /**
@@ -20,6 +22,8 @@ type AuthEnv = Pick<
   | "BETTER_AUTH_SECRET"
   | "GOOGLE_CLIENT_ID"
   | "GOOGLE_CLIENT_SECRET"
+  | "RESEND_API_KEY"
+  | "RESEND_EMAIL_FROM"
 >;
 
 /**
@@ -79,6 +83,16 @@ export function createAuth(
     // Email and password authentication
     emailAndPassword: {
       enabled: true,
+      sendResetPassword: async ({ user, url }) => {
+        await sendPasswordReset(env, { user, url });
+      },
+    },
+
+    // Email verification
+    emailVerification: {
+      sendVerificationEmail: async ({ user, url }) => {
+        await sendVerificationEmail(env, { user, url });
+      },
     },
 
     // OAuth providers
@@ -104,6 +118,14 @@ export function createAuth(
         // origin: URL where auth occurs (no trailing slash)
         origin: env.APP_ORIGIN,
       }),
+      emailOTP({
+        async sendVerificationOTP({ email, otp, type }) {
+          await sendOTP(env, { email, otp, type });
+        },
+        otpLength: 6,
+        expiresIn: 300, // 5 minutes
+        allowedAttempts: 3,
+      }),
     ],
 
     advanced: {

apps/api/lib/context.ts

@@ -5,6 +5,7 @@ import type { DbSchema } from "@repo/db";
 import type { CreateHTTPContextOptions } from "@trpc/server/adapters/standalone";
 import type { Session, User } from "better-auth/types";
 import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { Resend } from "resend";
 import type { Auth } from "./auth.js";
 import type { Env } from "./env.js";
 
@@ -80,6 +81,7 @@ export type AppContext = {
     db: PostgresJsDatabase<DbSchema>;
     dbDirect: PostgresJsDatabase<DbSchema>;
     auth: Auth;
+    resend?: Resend;
     session: Session | null;
     user: User | null;
   };