better-ts-stack 2.1.1 → 2.2.0

package/templates/modules/auth/nextjs/config.json

@@ -1,18 +1,24 @@
-{
-  "id": "auth",
-  "name": "Better Auth",
-  "description": "Better Auth for Next.js with optional Prisma or Drizzle adapter",
-  "type": "feature",
-  "dependencies": {
-    "@hookform/resolvers": "^5.9.2",
-    "better-auth": "^1.7.14",
-    "react-hook-form": "^7.91.0",
-    "zod": "^4.6.7"
-  },
-  "devDependencies": {},
-  "scripts": {},
-  "envVars": {
-    "BETTER_AUTH_SECRET": "please-change-me-to-a-random-string",
-    "BETTER_AUTH_URL": "http://localhost:3000"
-  }
-}
+{
+  "id": "auth",
+  "name": "Better Auth",
+  "description": "Better Auth with email verification, password reset, and GitHub and Google sign-in for Next.js with optional Prisma or Drizzle adapter",
+  "type": "feature",
+  "dependencies": {
+    "@hookform/resolvers": "^5.9.2",
+    "better-auth": "^1.7.14",
+    "react-hook-form": "^7.91.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {},
+  "scripts": {},
+  "envVars": {
+    "BETTER_AUTH_SECRET": "please-change-me-to-a-random-string",
+    "BETTER_AUTH_URL": "http://localhost:3000",
+    "GITHUB_CLIENT_ID": "",
+    "GITHUB_CLIENT_SECRET": "",
+    "GOOGLE_CLIENT_ID": "",
+    "GOOGLE_CLIENT_SECRET": "",
+    "RESEND_API_KEY": "",
+    "EMAIL_FROM": "onboarding@resend.dev"
+  }
+}

package/templates/modules/auth/nextjs/lib/auth-client.ts

@@ -1,3 +1,3 @@
-import { createAuthClient } from "better-auth/react";
-
-export const authClient = createAuthClient();
+import { createAuthClient } from "better-auth/react";
+
+export const authClient = createAuthClient();

package/templates/modules/auth/nextjs/lib/auth-schema.ts

@@ -1,8 +1,13 @@
 import { z } from "zod";
 
+const emailSchema = z.email("Enter a valid email address.");
+const passwordSchema = z
+  .string()
+  .min(8, "Password must be at least 8 characters.");
+
 export const signInSchema = z.object({
-  email: z.email("Enter a valid email address."),
-  password: z.string().min(8, "Password must be at least 8 characters."),
+  email: emailSchema,
+  password: passwordSchema,
 });
 
 export const signUpSchema = signInSchema.extend({
@@ -13,8 +18,28 @@ export const signUpSchema = signInSchema.extend({
     .max(50, "Name must be 50 characters or fewer."),
 });
 
+export const forgotPasswordSchema = z.object({ email: emailSchema });
+
+export const resetPasswordSchema = z
+  .object({ password: passwordSchema, confirmPassword: z.string() })
+  .refine((values) => values.password === values.confirmPassword, {
+    message: "Passwords do not match.",
+    path: ["confirmPassword"],
+  });
+
+export const changePasswordSchema = z.object({
+  currentPassword: z.string().min(1, "Enter your current password."),
+  newPassword: passwordSchema,
+});
+
 export type SignInValues = z.infer<typeof signInSchema>;
 export type SignUpValues = z.infer<typeof signUpSchema>;
+export type ForgotPasswordValues = z.infer<typeof forgotPasswordSchema>;
+export type ResetPasswordValues = z.infer<typeof resetPasswordSchema>;
+export type ChangePasswordValues = z.infer<typeof changePasswordSchema>;
+
+// Sign-in providers the auth server can turn on (see auth.ts)
+export type SocialProvider = "github" | "google";
 
 export function getAuthErrorMessage(error: unknown) {
   if (!error) {

package/templates/modules/auth/nextjs/lib/auth.ts.hbs

@@ -1,5 +1,9 @@
+import { after } from "next/server";
 import { betterAuth } from "better-auth";
 import { nextCookies } from "better-auth/next-js";
+
+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";
@@ -16,6 +20,18 @@ const client = new MongoClient(process.env.MONGODB_URI!);
 const db = client.db();
 {{/if}}
 
+// Sends the email after the response, so the request does not wait for it.
+// after() keeps a serverless function (such as on Vercel) running until the
+// email is sent. A failed email is logged 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 {
+  after(() =>
+    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" }),
@@ -30,8 +46,57 @@ export const auth = betterAuth({
   {{/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: [nextCookies()],
   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/nextjs/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/nextjs/lib/session.ts

@@ -0,0 +1,12 @@
+import { cache } from "react";
+
+import { headers } from "next/headers";
+
+import { auth } from "./auth";
+
+// The session of the current request, checked on the server. cache() runs the
+// lookup once per request, however many components ask for it, so each part of
+// a page can read the session inside its own <Suspense> boundary
+export const getSession = cache(async () =>
+  auth.api.getSession({ headers: await headers() })
+);

package/templates/modules/auth/tanstack/config.json

@@ -1,19 +1,25 @@
-{
-  "id": "auth",
-  "name": "Better Auth",
-  "description": "Better Auth for TanStack Start with optional Prisma, Drizzle, or MongoDB adapter",
-  "type": "feature",
-  "dependencies": {
-    "@hookform/resolvers": "^5.9.2",
-    "better-auth": "^1.7.14",
-    "dotenv": "^17.4.2",
-    "react-hook-form": "^7.91.0",
-    "zod": "^4.6.7"
-  },
-  "devDependencies": {},
-  "scripts": {},
-  "envVars": {
-    "BETTER_AUTH_SECRET": "please-change-me-to-a-random-string",
-    "BETTER_AUTH_URL": "http://localhost:3000"
-  }
-}
+{
+  "id": "auth",
+  "name": "Better Auth",
+  "description": "Better Auth with email verification, password reset, and GitHub and Google sign-in for TanStack Start with optional Prisma, Drizzle, or MongoDB adapter",
+  "type": "feature",
+  "dependencies": {
+    "@hookform/resolvers": "^5.9.2",
+    "better-auth": "^1.7.14",
+    "dotenv": "^17.4.2",
+    "react-hook-form": "^7.91.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {},
+  "scripts": {},
+  "envVars": {
+    "BETTER_AUTH_SECRET": "please-change-me-to-a-random-string",
+    "BETTER_AUTH_URL": "http://localhost:3000",
+    "GITHUB_CLIENT_ID": "",
+    "GITHUB_CLIENT_SECRET": "",
+    "GOOGLE_CLIENT_ID": "",
+    "GOOGLE_CLIENT_SECRET": "",
+    "RESEND_API_KEY": "",
+    "EMAIL_FROM": "onboarding@resend.dev"
+  }
+}

package/templates/modules/auth/tanstack/src/components/auth/change-password-form.tsx

@@ -0,0 +1,123 @@
+import { useState, useTransition } from "react";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { CircleAlert, CircleCheck } from "lucide-react";
+import { useForm } from "react-hook-form";
+
+import { authClient } from "~/lib/auth-client";
+import {
+  changePasswordSchema,
+  getAuthErrorMessage,
+  type ChangePasswordValues,
+} from "~/lib/auth-schema";
+import { Alert, AlertDescription } from "~/components/ui/alert";
+import { Button } from "~/components/ui/button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "~/components/ui/card";
+import {
+  Field,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+} from "~/components/ui/field";
+import { Input } from "~/components/ui/input";
+import { Spinner } from "~/components/ui/spinner";
+
+export function ChangePasswordForm() {
+  const [isPending, startTransition] = useTransition();
+  const [message, setMessage] = useState<{
+    text: string;
+    isError: boolean;
+  } | null>(null);
+  const form = useForm<ChangePasswordValues>({
+    resolver: zodResolver(changePasswordSchema),
+    defaultValues: { currentPassword: "", newPassword: "" },
+  });
+
+  const onSubmit = form.handleSubmit((values) => {
+    setMessage(null);
+
+    startTransition(async () => {
+      // Other devices are signed out; this one stays signed in
+      const result = await authClient.changePassword({
+        currentPassword: values.currentPassword,
+        newPassword: values.newPassword,
+        revokeOtherSessions: true,
+      });
+
+      if (result.error) {
+        setMessage({ text: getAuthErrorMessage(result.error), isError: true });
+        return;
+      }
+
+      form.reset();
+      setMessage({ text: "Password changed.", isError: false });
+    });
+  });
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Change password</CardTitle>
+        <CardDescription>
+          Other devices are signed out after the change.
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        <form onSubmit={onSubmit} noValidate>
+          <FieldGroup>
+            <Field
+              data-invalid={Boolean(form.formState.errors.currentPassword)}
+            >
+              <FieldLabel htmlFor="currentPassword">Current password</FieldLabel>
+              <Input
+                id="currentPassword"
+                type="password"
+                autoComplete="current-password"
+                aria-invalid={Boolean(form.formState.errors.currentPassword)}
+                {...form.register("currentPassword")}
+              />
+              <FieldError errors={[form.formState.errors.currentPassword]} />
+            </Field>
+
+            <Field data-invalid={Boolean(form.formState.errors.newPassword)}>
+              <FieldLabel htmlFor="newPassword">New password</FieldLabel>
+              <Input
+                id="newPassword"
+                type="password"
+                autoComplete="new-password"
+                aria-invalid={Boolean(form.formState.errors.newPassword)}
+                {...form.register("newPassword")}
+              />
+              <FieldError errors={[form.formState.errors.newPassword]} />
+            </Field>
+
+            {message ? (
+              <Alert variant={message.isError ? "destructive" : "default"}>
+                {message.isError ? <CircleAlert /> : <CircleCheck />}
+                <AlertDescription>{message.text}</AlertDescription>
+              </Alert>
+            ) : null}
+
+            <Field orientation="horizontal">
+              <Button type="submit" disabled={isPending}>
+                {isPending ? (
+                  <>
+                    <Spinner data-icon="inline-start" />
+                    Saving
+                  </>
+                ) : (
+                  "Change password"
+                )}
+              </Button>
+            </Field>
+          </FieldGroup>
+        </form>
+      </CardContent>
+    </Card>
+  );
+}

package/templates/modules/auth/tanstack/src/components/auth/email-verification-card.tsx

@@ -0,0 +1,89 @@
+import { useState, useTransition } from "react";
+import { BadgeCheck, MailWarning } from "lucide-react";
+
+import { authClient } from "~/lib/auth-client";
+import { getAuthErrorMessage } from "~/lib/auth-schema";
+import { Badge } from "~/components/ui/badge";
+import { Button } from "~/components/ui/button";
+import {
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "~/components/ui/card";
+import { Spinner } from "~/components/ui/spinner";
+
+// Shows whether the email address is verified, with a button to send the
+// verification email again
+export function EmailVerificationCard({
+  email,
+  emailVerified,
+}: {
+  email: string;
+  emailVerified: boolean;
+}) {
+  const [isPending, startTransition] = useTransition();
+  const [message, setMessage] = useState<string | null>(null);
+
+  function resend() {
+    setMessage(null);
+    startTransition(async () => {
+      const result = await authClient.sendVerificationEmail({
+        email,
+        callbackURL: "/dashboard",
+      });
+      setMessage(
+        result.error
+          ? getAuthErrorMessage(result.error)
+          : "Verification email sent. Without an email provider set up, the link is printed in the server terminal."
+      );
+    });
+  }
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>
+          {emailVerified ? "Email verified" : "Verify your email"}
+        </CardTitle>
+        <CardDescription>
+          {emailVerified
+            ? `${email} is confirmed.`
+            : `We sent a link to ${email}. Open it to confirm the address.`}
+        </CardDescription>
+        <CardAction>
+          {emailVerified ? (
+            <Badge variant="secondary">
+              <BadgeCheck data-icon="inline-start" />
+              Verified
+            </Badge>
+          ) : (
+            <Badge variant="outline">
+              <MailWarning data-icon="inline-start" />
+              Pending
+            </Badge>
+          )}
+        </CardAction>
+      </CardHeader>
+      {emailVerified ? null : (
+        <CardContent className="flex flex-col items-start gap-3">
+          <Button variant="outline" onClick={resend} disabled={isPending}>
+            {isPending ? (
+              <>
+                <Spinner data-icon="inline-start" />
+                Sending
+              </>
+            ) : (
+              "Send the email again"
+            )}
+          </Button>
+          {message ? (
+            <p className="text-sm text-muted-foreground">{message}</p>
+          ) : null}
+        </CardContent>
+      )}
+    </Card>
+  );
+}

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

@@ -0,0 +1,131 @@
+import { Link } from "@tanstack/react-router";
+import { useState, useTransition } from "react";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { CircleAlert, MailCheck } from "lucide-react";
+import { useForm } from "react-hook-form";
+
+import { authClient } from "~/lib/auth-client";
+import {
+  forgotPasswordSchema,
+  getAuthErrorMessage,
+  type ForgotPasswordValues,
+} from "~/lib/auth-schema";
+import { Alert, AlertDescription, AlertTitle } from "~/components/ui/alert";
+import { Button } from "~/components/ui/button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "~/components/ui/card";
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+} from "~/components/ui/field";
+import { Input } from "~/components/ui/input";
+import { Spinner } from "~/components/ui/spinner";
+
+export function ForgotPasswordForm() {
+  const [isPending, startTransition] = useTransition();
+  const [authError, setAuthError] = useState<string | null>(null);
+  const [isSent, setIsSent] = useState(false);
+  const form = useForm<ForgotPasswordValues>({
+    resolver: zodResolver(forgotPasswordSchema),
+    defaultValues: { email: "" },
+  });
+
+  const onSubmit = form.handleSubmit((values) => {
+    setAuthError(null);
+
+    startTransition(async () => {
+      // The link in the email opens /reset-password with a one-time token
+      const result = await authClient.requestPasswordReset({
+        email: values.email,
+        redirectTo: "/reset-password",
+      });
+
+      if (result.error) {
+        setAuthError(getAuthErrorMessage(result.error));
+        return;
+      }
+
+      setIsSent(true);
+    });
+  });
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Forgot your password?</CardTitle>
+        <CardDescription>
+          Enter your email and we will send you a link to choose a new one.
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        {isSent ? (
+          <FieldGroup>
+            <Alert>
+              <MailCheck />
+              <AlertTitle>Check your email</AlertTitle>
+              <AlertDescription>
+                If an account exists for that email, a reset link is on its
+                way. Without an email provider set up, the link is printed in
+                the server terminal.
+              </AlertDescription>
+            </Alert>
+            <FieldDescription className="text-center">
+              <Link to="/sign-in">Back to login</Link>
+            </FieldDescription>
+          </FieldGroup>
+        ) : (
+          <form onSubmit={onSubmit} noValidate>
+            <FieldGroup>
+              <Field data-invalid={Boolean(form.formState.errors.email)}>
+                <FieldLabel htmlFor="email">Email</FieldLabel>
+                <Input
+                  id="email"
+                  type="email"
+                  autoComplete="email"
+                  aria-invalid={Boolean(form.formState.errors.email)}
+                  placeholder="you@example.com"
+                  {...form.register("email")}
+                />
+                <FieldDescription>
+                  Use the email you registered with.
+                </FieldDescription>
+                <FieldError errors={[form.formState.errors.email]} />
+              </Field>
+
+              {authError ? (
+                <Alert variant="destructive">
+                  <CircleAlert />
+                  <AlertDescription>{authError}</AlertDescription>
+                </Alert>
+              ) : null}
+
+              <Field>
+                <Button type="submit" disabled={isPending}>
+                  {isPending ? (
+                    <>
+                      <Spinner data-icon="inline-start" />
+                      Sending link
+                    </>
+                  ) : (
+                    "Send reset link"
+                  )}
+                </Button>
+                <FieldDescription className="text-center">
+                  Remembered it? <Link to="/sign-in">Back to login</Link>
+                </FieldDescription>
+              </Field>
+            </FieldGroup>
+          </form>
+        )}
+      </CardContent>
+    </Card>
+  );
+}