better-ts-stack 2.1.1 → 2.2.0

package/templates/modules/auth/tanstack/src/lib/auth.ts.hbs

@@ -1,38 +1,98 @@
-import "dotenv/config";
-import { betterAuth } from "better-auth";
-import { tanstackStartCookies } from "better-auth/tanstack-start";
-{{#if (eq database 'prisma')}}
-import { prismaAdapter } from "better-auth/adapters/prisma";
-import client from "./prisma";
-{{/if}}
-{{#if (eq database 'drizzle')}}
-import { drizzleAdapter } from "better-auth/adapters/drizzle";
-import { db } from "./db";
-{{/if}}
-{{#if (eq database 'mongoose')}}
-import { mongodbAdapter } from "better-auth/adapters/mongodb";
-import { MongoClient } from "mongodb";
-
-const client = new MongoClient(process.env.MONGODB_URI!);
-const db = client.db();
-{{/if}}
-
-export const auth = betterAuth({
-  {{#if (eq database 'prisma')}}
-  database: prismaAdapter(client, { provider: "postgresql" }),
-  {{/if}}
-  {{#if (eq database 'drizzle')}}
-  database: drizzleAdapter(db, { provider: "pg" }),
-  {{/if}}
-  {{#if (eq database 'mongoose')}}
-  // Transactions require a replica set. Create user/session/account/verification
-  // collections before the first sign-up; see the database setup documentation.
-  database: mongodbAdapter(db, { client }),
-  {{/if}}
-  emailAndPassword: {
-    enabled: true,
-  },
-  plugins: [tanstackStartCookies()],
-  secret: process.env.BETTER_AUTH_SECRET,
-  baseURL: process.env.BETTER_AUTH_URL,
-});
+import "dotenv/config";
+import { betterAuth } from "better-auth";
+import { tanstackStartCookies } from "better-auth/tanstack-start";
+
+import type { SocialProvider } from "./auth-schema";
+import { sendEmail } from "./email";
+{{#if (eq database 'prisma')}}
+import { prismaAdapter } from "better-auth/adapters/prisma";
+import client from "./prisma";
+{{/if}}
+{{#if (eq database 'drizzle')}}
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { db } from "./db";
+{{/if}}
+{{#if (eq database 'mongoose')}}
+import { mongodbAdapter } from "better-auth/adapters/mongodb";
+import { MongoClient } from "mongodb";
+
+const client = new MongoClient(process.env.MONGODB_URI!);
+const db = client.db();
+{{/if}}
+
+// Reports a failed email instead of failing the request: the sign-up or reset
+// already happened, and the user can ask for the email again
+function deliver(email: Parameters<typeof sendEmail>[0]): void {
+  sendEmail(email).catch((error: unknown) => {
+    console.error(`Could not send "${email.subject}" to ${email.to}:`, error);
+  });
+}
+
+export const auth = betterAuth({
+  {{#if (eq database 'prisma')}}
+  database: prismaAdapter(client, { provider: "postgresql" }),
+  {{/if}}
+  {{#if (eq database 'drizzle')}}
+  database: drizzleAdapter(db, { provider: "pg" }),
+  {{/if}}
+  {{#if (eq database 'mongoose')}}
+  // Transactions require a replica set. Create user/session/account/verification
+  // collections before the first sign-up; see the database setup documentation.
+  database: mongodbAdapter(db, { client }),
+  {{/if}}
+  emailAndPassword: {
+    enabled: true,
+    // Set to true to block sign-in until the email address is verified
+    requireEmailVerification: false,
+    // A reset signs the user out everywhere
+    revokeSessionsOnPasswordReset: true,
+    sendResetPassword: async ({ user, url }) => {
+      deliver({
+        to: user.email,
+        subject: "Reset your password",
+        text: `Open this link to choose a new password:
+${url}`,
+      });
+    },
+  },
+  emailVerification: {
+    sendOnSignUp: true,
+    autoSignInAfterVerification: true,
+    sendVerificationEmail: async ({ user, url }) => {
+      deliver({
+        to: user.email,
+        subject: "Verify your email address",
+        text: `Open this link to verify your email address:
+${url}`,
+      });
+    },
+  },
+  // Each provider is turned on once its client ID and secret are set
+  socialProviders: {
+    ...(process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET
+      ? {
+          github: {
+            clientId: process.env.GITHUB_CLIENT_ID,
+            clientSecret: process.env.GITHUB_CLIENT_SECRET,
+          },
+        }
+      : {}),
+    ...(process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET
+      ? {
+          google: {
+            clientId: process.env.GOOGLE_CLIENT_ID,
+            clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+          },
+        }
+      : {}),
+  },
+  plugins: [tanstackStartCookies()],
+  secret: process.env.BETTER_AUTH_SECRET,
+  baseURL: process.env.BETTER_AUTH_URL,
+});
+
+// The providers turned on above; the sign-in and sign-up pages show a button
+// for each
+export const socialProviders = Object.keys(
+  auth.options.socialProviders
+) as SocialProvider[];

package/templates/modules/auth/tanstack/src/lib/email.ts

@@ -0,0 +1,43 @@
+// Sends through Resend when RESEND_API_KEY is set. Without it the email is
+// printed to the server log, so verification and reset links can be copied
+// from the terminal during development
+export async function sendEmail({
+  to,
+  subject,
+  text,
+}: {
+  to: string;
+  subject: string;
+  text: string;
+}): Promise<void> {
+  const apiKey = process.env.RESEND_API_KEY;
+
+  if (!apiKey) {
+    console.log(`
+--- Email to ${to}: ${subject}
+${text}
+---
+`);
+    return;
+  }
+
+  const response = await fetch("https://api.resend.com/emails", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      from: process.env.EMAIL_FROM || "onboarding@resend.dev",
+      to,
+      subject,
+      text,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Resend rejected the email (${response.status}): ${await response.text()}`
+    );
+  }
+}

package/templates/modules/auth/tanstack/src/routeTree.gen.ts

@@ -11,6 +11,8 @@
 import { Route as rootRouteImport } from './routes/__root'
 import { Route as IndexRouteImport } from './routes/index'
 import { Route as DashboardRouteImport } from './routes/dashboard'
+import { Route as ForgotPasswordRouteImport } from './routes/forgot-password'
+import { Route as ResetPasswordRouteImport } from './routes/reset-password'
 import { Route as SignInRouteImport } from './routes/sign-in'
 import { Route as SignUpRouteImport } from './routes/sign-up'
 import { Route as ApiAuthSplatRouteImport } from './routes/api/auth/$'
@@ -25,6 +27,16 @@ const DashboardRoute = DashboardRouteImport.update({
   path: '/dashboard',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ForgotPasswordRoute = ForgotPasswordRouteImport.update({
+  id: '/forgot-password',
+  path: '/forgot-password',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ResetPasswordRoute = ResetPasswordRouteImport.update({
+  id: '/reset-password',
+  path: '/reset-password',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const SignInRoute = SignInRouteImport.update({
   id: '/sign-in',
   path: '/sign-in',
@@ -44,6 +56,8 @@ const ApiAuthSplatRoute = ApiAuthSplatRouteImport.update({
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
   '/dashboard': typeof DashboardRoute
+  '/forgot-password': typeof ForgotPasswordRoute
+  '/reset-password': typeof ResetPasswordRoute
   '/sign-in': typeof SignInRoute
   '/sign-up': typeof SignUpRoute
   '/api/auth/$': typeof ApiAuthSplatRoute
@@ -51,6 +65,8 @@ export interface FileRoutesByFullPath {
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
   '/dashboard': typeof DashboardRoute
+  '/forgot-password': typeof ForgotPasswordRoute
+  '/reset-password': typeof ResetPasswordRoute
   '/sign-in': typeof SignInRoute
   '/sign-up': typeof SignUpRoute
   '/api/auth/$': typeof ApiAuthSplatRoute
@@ -59,21 +75,47 @@ export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
   '/dashboard': typeof DashboardRoute
+  '/forgot-password': typeof ForgotPasswordRoute
+  '/reset-password': typeof ResetPasswordRoute
   '/sign-in': typeof SignInRoute
   '/sign-up': typeof SignUpRoute
   '/api/auth/$': typeof ApiAuthSplatRoute
 }
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
-  fullPaths: '/' | '/dashboard' | '/sign-in' | '/sign-up' | '/api/auth/$'
+  fullPaths:
+    | '/'
+    | '/dashboard'
+    | '/forgot-password'
+    | '/reset-password'
+    | '/sign-in'
+    | '/sign-up'
+    | '/api/auth/$'
   fileRoutesByTo: FileRoutesByTo
-  to: '/' | '/dashboard' | '/sign-in' | '/sign-up' | '/api/auth/$'
-  id: '__root__' | '/' | '/dashboard' | '/sign-in' | '/sign-up' | '/api/auth/$'
+  to:
+    | '/'
+    | '/dashboard'
+    | '/forgot-password'
+    | '/reset-password'
+    | '/sign-in'
+    | '/sign-up'
+    | '/api/auth/$'
+  id:
+    | '__root__'
+    | '/'
+    | '/dashboard'
+    | '/forgot-password'
+    | '/reset-password'
+    | '/sign-in'
+    | '/sign-up'
+    | '/api/auth/$'
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
   DashboardRoute: typeof DashboardRoute
+  ForgotPasswordRoute: typeof ForgotPasswordRoute
+  ResetPasswordRoute: typeof ResetPasswordRoute
   SignInRoute: typeof SignInRoute
   SignUpRoute: typeof SignUpRoute
   ApiAuthSplatRoute: typeof ApiAuthSplatRoute
@@ -95,6 +137,20 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof DashboardRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/forgot-password': {
+      id: '/forgot-password'
+      path: '/forgot-password'
+      fullPath: '/forgot-password'
+      preLoaderRoute: typeof ForgotPasswordRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/reset-password': {
+      id: '/reset-password'
+      path: '/reset-password'
+      fullPath: '/reset-password'
+      preLoaderRoute: typeof ResetPasswordRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/sign-in': {
       id: '/sign-in'
       path: '/sign-in'
@@ -122,6 +178,8 @@ declare module '@tanstack/react-router' {
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
   DashboardRoute: DashboardRoute,
+  ForgotPasswordRoute: ForgotPasswordRoute,
+  ResetPasswordRoute: ResetPasswordRoute,
   SignInRoute: SignInRoute,
   SignUpRoute: SignUpRoute,
   ApiAuthSplatRoute: ApiAuthSplatRoute,

package/templates/modules/auth/tanstack/src/routes/api/auth/$.ts

@@ -1,16 +1,16 @@
-import { createFileRoute } from "@tanstack/react-router";
-
-import { auth } from "~/lib/auth";
-
-export const Route = createFileRoute("/api/auth/$")({
-  server: {
-    handlers: {
-      GET: async ({ request }: { request: Request }) => {
-        return await auth.handler(request);
-      },
-      POST: async ({ request }: { request: Request }) => {
-        return await auth.handler(request);
-      },
-    },
-  },
+import { createFileRoute } from "@tanstack/react-router";
+
+import { auth } from "~/lib/auth";
+
+export const Route = createFileRoute("/api/auth/$")({
+  server: {
+    handlers: {
+      GET: async ({ request }: { request: Request }) => {
+        return await auth.handler(request);
+      },
+      POST: async ({ request }: { request: Request }) => {
+        return await auth.handler(request);
+      },
+    },
+  },
 });

package/templates/modules/auth/tanstack/src/routes/dashboard.tsx

@@ -1,111 +1,119 @@
-import { createFileRoute, redirect } from "@tanstack/react-router";
-import { Link } from "@tanstack/react-router";
-import { ArrowRight, ShieldCheck } from "lucide-react";
-
-import { SignOutButton } from "~/components/auth/sign-out-button";
-import { buttonVariants } from "~/components/ui/button";
-import {
-  Card,
-  CardContent,
-  CardDescription,
-  CardHeader,
-  CardTitle,
-} from "~/components/ui/card";
-import { getSession } from "~/lib/auth-functions";
-import { cn } from "~/lib/utils";
-
-export const Route = createFileRoute("/dashboard")({
-  beforeLoad: async () => {
-    const session = await getSession();
-
-    if (!session) {
-      throw redirect({ to: "/sign-in" });
-    }
-
-    return { user: session.user };
-  },
-  component: Dashboard,
-});
-
-function Dashboard() {
-  const user = Route.useRouteContext({ select: (ctx) => ctx.user });
-
-  return (
-    <main className="min-h-screen bg-[linear-gradient(180deg,_#f8fafc_0%,_#eef2ff_100%)] px-6 py-16 sm:px-10">
-      <div className="mx-auto max-w-5xl space-y-8">
-        <header className="flex flex-col gap-6 rounded-[2rem] border border-white/70 bg-white/85 p-8 shadow-xl shadow-slate-200/60 backdrop-blur md:flex-row md:items-end md:justify-between">
-          <div className="space-y-3">
-            <span className="inline-flex items-center gap-2 rounded-full bg-emerald-50 px-3 py-1 text-xs font-medium uppercase tracking-[0.24em] text-emerald-700">
-              <ShieldCheck className="size-4" />
-              Authenticated session
-            </span>
-            <div className="space-y-1">
-              <h1 className="text-3xl font-semibold tracking-tight text-slate-950">
-                Welcome {user.name}
-              </h1>
-              <p className="text-sm text-slate-600">{user.email}</p>
-            </div>
-          </div>
-          <SignOutButton />
-        </header>
-
-        <section className="grid gap-5 md:grid-cols-2">
-          <Card>
-            <CardHeader>
-              <CardTitle>Protected route example</CardTitle>
-              <CardDescription>
-                This page verifies the session on the server before rendering any
-                content.
-              </CardDescription>
-            </CardHeader>
-            <CardContent className="space-y-4 text-sm text-slate-600">
-              <p>
-                The route guard calls{" "}
-                <code className="font-mono text-slate-900">getSession()</code> in
-                <code className="font-mono text-slate-900"> beforeLoad</code>,
-                which reads the cookie headers server-side via{" "}
-                <code className="font-mono text-slate-900">
-                  auth.api.getSession
-                </code>{" "}
-                on every render and navigation.
-              </p>
-              <p>
-                That keeps route protection aligned with Better Auth&apos;s
-                TanStack Start guidance while staying easy to extend.
-              </p>
-            </CardContent>
-          </Card>
-
-          <Card>
-            <CardHeader>
-              <CardTitle>Suggested next steps</CardTitle>
-              <CardDescription>
-                Keep the generated auth flow, then customize the app around your
-                product.
-              </CardDescription>
-            </CardHeader>
-            <CardContent className="space-y-3 text-sm text-slate-600">
-              <p>
-                Replace the demo dashboard with your first authenticated page.
-              </p>
-              <p>Extend the schema with profile or onboarding fields.</p>
-              <p>
-                Add provider-based auth or email verification later if needed.
-              </p>
-              <Link
-                to="/"
-                className={cn(
-                  buttonVariants({ variant: "outline" }),
-                  "w-fit gap-2"
-                )}
-              >
-                Back to home
-                <ArrowRight className="size-4" />
-              </Link>
-            </CardContent>
-          </Card>
-        </section>
-      </div>
-    </main>
-  );
-}
+import { createFileRoute, Link, redirect } from "@tanstack/react-router";
+import { ArrowRight, ShieldCheck } from "lucide-react";
+
+import { ChangePasswordForm } from "~/components/auth/change-password-form";
+import { EmailVerificationCard } from "~/components/auth/email-verification-card";
+import { SignOutButton } from "~/components/auth/sign-out-button";
+import { Badge } from "~/components/ui/badge";
+import { Button } from "~/components/ui/button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from "~/components/ui/card";
+import { getSession } from "~/lib/auth-functions";
+
+export const Route = createFileRoute("/dashboard")({
+  beforeLoad: async () => {
+    const session = await getSession();
+
+    if (!session) {
+      throw redirect({ to: "/sign-in" });
+    }
+
+    return { user: session.user };
+  },
+  component: Dashboard,
+});
+
+function Dashboard() {
+  const user = Route.useRouteContext({ select: (ctx) => ctx.user });
+
+  return (
+    <main className="min-h-svh bg-muted px-6 py-16 sm:px-10">
+      <div className="mx-auto flex max-w-5xl flex-col gap-8">
+        <header className="flex flex-col gap-6 md:flex-row md:items-end md:justify-between">
+          <div className="flex flex-col gap-3">
+            <Badge variant="secondary">
+              <ShieldCheck data-icon="inline-start" />
+              Authenticated session
+            </Badge>
+            <div className="flex flex-col gap-1">
+              <h1 className="text-3xl font-semibold tracking-tight">
+                Welcome {user.name}
+              </h1>
+              <p className="text-sm text-muted-foreground">{user.email}</p>
+            </div>
+          </div>
+          <SignOutButton />
+        </header>
+
+        <section className="grid gap-5 md:grid-cols-2">
+          <EmailVerificationCard
+            email={user.email}
+            emailVerified={user.emailVerified}
+          />
+          <ChangePasswordForm />
+          <Card>
+            <CardHeader>
+              <CardTitle>Protected route example</CardTitle>
+              <CardDescription>
+                This page verifies the session on the server before rendering
+                any content.
+              </CardDescription>
+            </CardHeader>
+            <CardContent className="flex flex-col gap-4 text-muted-foreground">
+              <p>
+                The route guard calls{" "}
+                <code className="font-mono text-foreground">getSession()</code>{" "}
+                in <code className="font-mono text-foreground">beforeLoad</code>,
+                which reads the cookie headers server-side via{" "}
+                <code className="font-mono text-foreground">
+                  auth.api.getSession
+                </code>{" "}
+                on every render and navigation.
+              </p>
+              <p>
+                That keeps route protection aligned with Better Auth&apos;s
+                TanStack Start guidance while staying easy to extend.
+              </p>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Suggested next steps</CardTitle>
+              <CardDescription>
+                Keep the generated auth flow, then customize the app around your
+                product.
+              </CardDescription>
+            </CardHeader>
+            <CardContent className="flex flex-col gap-3 text-muted-foreground">
+              <p>
+                Replace the demo dashboard with your first authenticated page.
+              </p>
+              <p>Extend the schema with profile or onboarding fields.</p>
+              <p>
+                Add a GitHub or Google client ID and secret to .env to turn on
+                social sign-in, and RESEND_API_KEY to send real emails.
+              </p>
+            </CardContent>
+            <CardFooter>
+              <Button
+                variant="outline"
+                nativeButton={false}
+                render={<Link to="/" />}
+              >
+                Back to home
+                <ArrowRight data-icon="inline-end" />
+              </Button>
+            </CardFooter>
+          </Card>
+        </section>
+      </div>
+    </main>
+  );
+}

package/templates/modules/auth/tanstack/src/routes/forgot-password.tsx

@@ -0,0 +1,17 @@
+import { createFileRoute } from "@tanstack/react-router";
+
+import { ForgotPasswordForm } from "~/components/auth/forgot-password-form";
+
+export const Route = createFileRoute("/forgot-password")({
+  component: ForgotPasswordPage,
+});
+
+function ForgotPasswordPage() {
+  return (
+    <main className="flex min-h-svh items-center justify-center bg-muted p-6 md:p-10">
+      <div className="w-full max-w-md">
+        <ForgotPasswordForm />
+      </div>
+    </main>
+  );
+}

package/templates/modules/auth/tanstack/src/routes/reset-password.tsx

@@ -0,0 +1,25 @@
+import { createFileRoute } from "@tanstack/react-router";
+
+import { ResetPasswordForm } from "~/components/auth/reset-password-form";
+
+// The link in the reset email lands here with ?token=..., or with ?error=...
+// when the token is invalid or has expired
+export const Route = createFileRoute("/reset-password")({
+  validateSearch: (search: Record<string, unknown>) => ({
+    token: typeof search.token === "string" ? search.token : undefined,
+    error: typeof search.error === "string" ? search.error : undefined,
+  }),
+  component: ResetPasswordPage,
+});
+
+function ResetPasswordPage() {
+  const { token, error } = Route.useSearch();
+
+  return (
+    <main className="flex min-h-svh items-center justify-center bg-muted p-6 md:p-10">
+      <div className="w-full max-w-md">
+        <ResetPasswordForm token={error ? null : (token ?? null)} />
+      </div>
+    </main>
+  );
+}