better-ts-stack 2.1.2 → 2.2.0

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

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

package/templates/modules/auth/express/src/middleware/requireAuth.ts

@@ -0,0 +1,29 @@
+import { fromNodeHeaders } from "better-auth/node";
+import type { NextFunction, Request, Response } from "express";
+
+import { auth, type Session } from "../lib/auth";
+
+// Accepts a session cookie or an "Authorization: Bearer <token>" header and
+// stores the session in res.locals.session; answers 401 without one
+export function requireAuth(
+  req: Request,
+  res: Response,
+  next: NextFunction
+): void {
+  auth.api
+    .getSession({ headers: fromNodeHeaders(req.headers) })
+    .then((session) => {
+      if (!session) {
+        res.status(401).json({ error: "Unauthorized" });
+        return;
+      }
+      res.locals.session = session;
+      next();
+    })
+    .catch(next);
+}
+
+// The session requireAuth stored, for handlers that run after it
+export function getSession(res: Response): Session {
+  return res.locals.session as Session;
+}

package/templates/modules/auth/express/src/routes/me.ts

@@ -0,0 +1,13 @@
+import { Request, Response, Router } from "express";
+
+import { getSession, requireAuth } from "../middleware/requireAuth";
+
+const router: Router = Router();
+
+// Example of a protected route: returns the signed-in user
+router.get("/", requireAuth, (_req: Request, res: Response) => {
+  const { user, session } = getSession(res);
+  res.status(200).json({ user, session: { expiresAt: session.expiresAt } });
+});
+
+export default router;

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

@@ -1,20 +1,22 @@
 {
   "id": "auth",
-  "name": "JWT Auth",
-  "description": "JWT authentication for NestJS with bcrypt password hashing",
+  "name": "Better Auth",
+  "description": "Better Auth for NestJS: email and password, email verification, password reset, GitHub and Google sign-in, and bearer tokens",
   "type": "feature",
   "dependencies": {
-    "bcrypt": "^6.0.0",
-    "jsonwebtoken": "^9.0.3",
-    "zod": "^4.6.7"
-  },
-  "devDependencies": {
-    "@types/bcrypt": "^6.0.0",
-    "@types/jsonwebtoken": "^9.0.10"
+    "@thallesp/nestjs-better-auth": "^2.8.0",
+    "better-auth": "^1.7.18"
   },
+  "devDependencies": {},
   "scripts": {},
   "envVars": {
-    "JWT_SECRET": "please-change-me",
-    "JWT_EXPIRES_IN": "1h"
+    "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/nestjs/src/auth/auth.module.ts.hbs

@@ -1,22 +1,72 @@
-import { Module } from "@nestjs/common";
 {{#if (eq database 'mongoose')}}
-import { MongooseModule } from "@nestjs/mongoose";
+import {
+  Injectable,
+  Module,
+  type OnApplicationShutdown,
+} from "@nestjs/common";
+{{/if}}
+import { AuthModule as BetterAuthModule } from "@thallesp/nestjs-better-auth";
+import type { Request, Response } from "express";
+{{#if (eq database 'mongoose')}}
+import { MongoClient } from "mongodb";
 {{/if}}
 
+{{#if (eq database 'drizzle')}}
+import { type Database, DRIZZLE } from "../database/database.module.js";
+{{/if}}
 {{#if (eq database 'mongoose')}}
-import { User, UserSchema } from "../users/user.schema.js";
+import { env } from "../env.js";
 {{/if}}
-import { AuthController } from "./auth.controller.js";
-import { AuthService } from "./auth.service.js";
-import { UsersService } from "./users.service.js";
+{{#if (eq database 'prisma')}}
+import { PrismaService } from "../prisma/prisma.service.js";
+{{/if}}
+import { createAuth } from "./auth.js";
+
+{{#if (eq database 'mongoose')}}
+// Better Auth talks to MongoDB through the driver, next to Mongoose
+const mongoClient = new MongoClient(env.MONGODB_URI);
 
-@Module({
+@Injectable()
+class MongoClientShutdown implements OnApplicationShutdown {
+  onApplicationShutdown(): Promise<void> {
+    return mongoClient.close();
+  }
+}
+
+@Module({ providers: [MongoClientShutdown] })
+class MongoClientModule {}
+
+{{/if}}
+// Mounts Better Auth on /api/auth and protects every other route: add
+// @AllowAnonymous() to a controller or route that should stay public
+export const AuthModule = BetterAuthModule.forRootAsync({
+  {{#if (eq database 'prisma')}}
+  inject: [PrismaService],
+  useFactory: (prisma: PrismaService) => ({
+    auth: createAuth(prisma),
+  {{/if}}
+  {{#if (eq database 'drizzle')}}
+  inject: [DRIZZLE],
+  useFactory: (db: Database) => ({
+    auth: createAuth(db),
+  {{/if}}
   {{#if (eq database 'mongoose')}}
-  imports: [
-    MongooseModule.forFeature([{ name: User.name, schema: UserSchema }]),
-  ],
+  imports: [MongoClientModule],
+  useFactory: () => ({
+    auth: createAuth(mongoClient.db()),
+  {{/if}}
+  {{#if (eq database 'none')}}
+  useFactory: () => ({
+    auth: createAuth(),
   {{/if}}
-  controllers: [AuthController],
-  providers: [AuthService, UsersService],
-})
-export class AuthModule {}
+    // CORS stays with app.enableCors() in main.ts, which reads CORS_ORIGIN
+    disableTrustedOriginsCors: true,
+    // Better Auth reads the client IP for its rate limits from this header. It
+    // is set from req.ip on every request, so a client cannot pick its own
+    // value. Behind a reverse proxy, enable "trust proxy" for the real client IP
+    middleware: (req: Request, _res: Response, next: () => void) => {
+      req.headers["x-client-ip"] = req.ip;
+      next();
+    },
+  }),
+});

package/templates/modules/auth/nestjs/src/auth/auth.ts.hbs

@@ -0,0 +1,152 @@
+import { betterAuth } from "better-auth";
+{{#if (eq database 'none')}}
+import { memoryAdapter } from "better-auth/adapters/memory";
+{{/if}}
+{{#if (eq database 'prisma')}}
+import { prismaAdapter } from "better-auth/adapters/prisma";
+{{/if}}
+{{#if (eq database 'drizzle')}}
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+{{/if}}
+{{#if (eq database 'mongoose')}}
+import { mongodbAdapter } from "better-auth/adapters/mongodb";
+{{/if}}
+import { bearer } from "better-auth/plugins";
+{{#if (eq database 'mongoose')}}
+import type { Db } from "mongodb";
+{{/if}}
+
+{{#if (eq database 'drizzle')}}
+import type { Database } from "../database/database.module.js";
+{{/if}}
+import { env } from "../env.js";
+{{#if (eq database 'prisma')}}
+import type { PrismaService } from "../prisma/prisma.service.js";
+{{/if}}
+import { sendEmail } from "./email.js";
+
+{{#if (eq database 'none')}}
+// In-memory store for trying the API out: users and sessions are lost on
+// restart, so add a database before going to production
+const memoryDb = { user: [], session: [], account: [], verification: [] };
+
+{{/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);
+  });
+}
+
+// Points a verification link at the API itself when the client gave no page
+// to return to, so opening it answers with JSON instead of a redirect to "/"
+function withoutDefaultCallback(url: string): string {
+  const link = new URL(url);
+  if (link.searchParams.get("callbackURL") === "/") {
+    link.searchParams.delete("callbackURL");
+  }
+  return link.toString();
+}
+
+// Builds the Better Auth server; auth.module.ts calls it with the database
+{{#if (eq database 'none')}}
+export function createAuth() {
+{{/if}}
+{{#if (eq database 'prisma')}}
+export function createAuth(prisma: PrismaService) {
+{{/if}}
+{{#if (eq database 'drizzle')}}
+export function createAuth(db: Database) {
+{{/if}}
+{{#if (eq database 'mongoose')}}
+export function createAuth(db: Db) {
+{{/if}}
+  return betterAuth({
+    {{#if (eq database 'none')}}
+    database: memoryAdapter(memoryDb),
+    {{/if}}
+    {{#if (eq database 'prisma')}}
+    database: prismaAdapter(prisma, { provider: "postgresql" }),
+    {{/if}}
+    {{#if (eq database 'drizzle')}}
+    database: drizzleAdapter(db, { provider: "pg" }),
+    {{/if}}
+    {{#if (eq database 'mongoose')}}
+    // Without the client, writes run without transactions, which a standalone
+    // MongoDB server (no replica set) does not support
+    database: mongodbAdapter(db),
+    {{/if}}
+    secret: env.BETTER_AUTH_SECRET,
+    baseURL: env.BETTER_AUTH_URL,
+    // Browser apps on these origins may call the auth routes with cookies
+    trustedOrigins: typeof env.CORS_ORIGIN === "string" ? [] : env.CORS_ORIGIN,
+    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: ({ user, url, token }) => {
+        deliver({
+          to: user.email,
+          subject: "Reset your password",
+          text: `Open this link to choose a new password:\n${url}\n\nOr send this token to POST /api/auth/reset-password: ${token}`,
+        });
+        return Promise.resolve();
+      },
+    },
+    emailVerification: {
+      sendOnSignUp: true,
+      autoSignInAfterVerification: true,
+      sendVerificationEmail: ({ user, url }) => {
+        deliver({
+          to: user.email,
+          subject: "Verify your email address",
+          text: `Open this link to verify your email address:\n${withoutDefaultCallback(url)}`,
+        });
+        return Promise.resolve();
+      },
+    },
+    // Each provider is turned on once its client ID and secret are set
+    socialProviders: {
+      ...(env.GITHUB_CLIENT_ID && env.GITHUB_CLIENT_SECRET
+        ? {
+            github: {
+              clientId: env.GITHUB_CLIENT_ID,
+              clientSecret: env.GITHUB_CLIENT_SECRET,
+            },
+          }
+        : {}),
+      ...(env.GOOGLE_CLIENT_ID && env.GOOGLE_CLIENT_SECRET
+        ? {
+            google: {
+              clientId: env.GOOGLE_CLIENT_ID,
+              clientSecret: env.GOOGLE_CLIENT_SECRET,
+            },
+          }
+        : {}),
+    },
+    // Clients without cookies send "Authorization: Bearer <token>"; the token
+    // comes back in the set-auth-token header of sign-in and sign-up
+    plugins: [bearer()],
+    {{#if useRateLimit}}
+    // Sign-up, sign-in, and password reset: 10 attempts per client IP in 15
+    // minutes, against password guessing
+    rateLimit: {
+      enabled: true,
+      window: 15 * 60,
+      max: 100,
+      customRules: {
+        "/sign-in/*": { window: 15 * 60, max: 10 },
+        "/sign-up/*": { window: 15 * 60, max: 10 },
+        "/request-password-reset": { window: 15 * 60, max: 10 },
+      },
+    },
+    {{/if}}
+    advanced: {
+      // Set from req.ip on every request (see auth.module.ts)
+      ipAddress: { ipAddressHeaders: ["x-client-ip"] },
+    },
+  });
+}

package/templates/modules/auth/nestjs/src/auth/email.ts

@@ -0,0 +1,37 @@
+import { env } from "../env.js";
+
+interface Email {
+  to: string;
+  subject: string;
+  text: string;
+}
+
+if (!env.RESEND_API_KEY && process.env.NODE_ENV === "production") {
+  console.warn(
+    "RESEND_API_KEY is not set: emails are printed to the log instead of sent"
+  );
+}
+
+// Sends through Resend when RESEND_API_KEY is set. Without it the email is
+// printed, so verification and reset links can be copied from the terminal
+export async function sendEmail({ to, subject, text }: Email): Promise<void> {
+  if (!env.RESEND_API_KEY) {
+    console.log(`\n--- Email to ${to}: ${subject}\n${text}\n---\n`);
+    return;
+  }
+
+  const response = await fetch("https://api.resend.com/emails", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${env.RESEND_API_KEY}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ from: env.EMAIL_FROM, to, subject, text }),
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Resend rejected the email (${response.status}): ${await response.text()}`
+    );
+  }
+}

package/templates/modules/auth/nestjs/src/me/me.controller.ts

@@ -0,0 +1,15 @@
+import { Controller, Get } from "@nestjs/common";
+import { Session, type UserSession } from "@thallesp/nestjs-better-auth";
+
+// Example of a protected route: the global auth guard answers 401 without a
+// session cookie or an "Authorization: Bearer <token>" header
+@Controller("api/me")
+export class MeController {
+  @Get()
+  me(@Session() { user, session }: UserSession): {
+    user: UserSession["user"];
+    session: { expiresAt: Date };
+  } {
+    return { user, session: { expiresAt: session.expiresAt } };
+  }
+}

package/templates/modules/auth/nextjs/app/dashboard/page.tsx

@@ -1,69 +1,117 @@
+import { Suspense } from "react";
+
 import Link from "next/link";
-import { headers } from "next/headers";
 import { redirect } from "next/navigation";
+
 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 { buttonVariants } from "@/components/ui/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 { auth } from "@/lib/auth";
-import { cn } from "@/lib/utils";
+import { Skeleton } from "@/components/ui/skeleton";
+import { getSession } from "@/lib/session";
 
-export default async function DashboardPage() {
-  const session = await auth.api.getSession({
-    headers: await headers(),
-  });
+// The parts that need the user wait for the session in their own <Suspense>
+// boundary, so the rest of the page is sent without waiting for it
+async function DashboardHeader() {
+  const session = await getSession();
 
+  // proxy.ts already sent visitors without a session cookie to /sign-in; this
+  // catches an expired or revoked session
   if (!session) {
     redirect("/sign-in");
   }
 
   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 {session.user.name}
-              </h1>
-              <p className="text-sm text-slate-600">{session.user.email}</p>
-            </div>
-          </div>
-          <SignOutButton />
-        </header>
+    <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 {session.user.name}
+          </h1>
+          <p className="text-sm text-muted-foreground">{session.user.email}</p>
+        </div>
+      </div>
+      <SignOutButton />
+    </header>
+  );
+}
+
+function DashboardHeaderSkeleton() {
+  return (
+    <div className="flex flex-col gap-3" aria-busy="true">
+      <Skeleton className="h-5 w-44" />
+      <Skeleton className="h-9 w-64" />
+      <Skeleton className="h-4 w-40" />
+    </div>
+  );
+}
+
+async function EmailVerification() {
+  const session = await getSession();
+
+  return session ? (
+    <EmailVerificationCard
+      email={session.user.email}
+      emailVerified={session.user.emailVerified}
+    />
+  ) : null;
+}
+
+export default function DashboardPage() {
+  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">
+        <Suspense fallback={<DashboardHeaderSkeleton />}>
+          <DashboardHeader />
+        </Suspense>
 
         <section className="grid gap-5 md:grid-cols-2">
+          <Suspense fallback={<Skeleton className="h-40 rounded-xl" />}>
+            <EmailVerification />
+          </Suspense>
+          <ChangePasswordForm />
           <Card>
             <CardHeader>
               <CardTitle>Protected route example</CardTitle>
               <CardDescription>
-                This page verifies the session on the server before rendering any
-                content.
+                The page is sent right away; the parts that need the user stream
+                in once the server has checked the session.
               </CardDescription>
             </CardHeader>
-            <CardContent className="space-y-4 text-sm text-slate-600">
+            <CardContent className="flex flex-col gap-4 text-muted-foreground">
               <p>
-                The generated proxy only performs an optimistic cookie check. The
-                authoritative guard happens here with{" "}
-                <code className="font-mono text-slate-900">
-                  auth.api.getSession({"{"} headers: await headers() {"}"})
-                </code>
-                .
+                <code className="font-mono text-foreground">proxy.ts</code>{" "}
+                sends visitors without a session cookie to the sign-in page.
+                Each part that needs the user calls{" "}
+                <code className="font-mono text-foreground">getSession()</code>{" "}
+                from{" "}
+                <code className="font-mono text-foreground">
+                  lib/session.ts
+                </code>{" "}
+                inside its own{" "}
+                <code className="font-mono text-foreground">
+                  &lt;Suspense&gt;
+                </code>{" "}
+                boundary, and the session is looked up once per request.
               </p>
               <p>
-                That keeps route protection aligned with Better Auth&apos;s
-                Next.js guidance while staying easy to extend.
+                Check the session on the server like this in every protected
+                page, route handler, and server action.
               </p>
             </CardContent>
           </Card>
@@ -76,18 +124,26 @@ export default async function DashboardPage() {
                 product.
               </CardDescription>
             </CardHeader>
-            <CardContent className="space-y-3 text-sm text-slate-600">
-              <p>Replace the demo dashboard with your first authenticated page.</p>
+            <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 provider-based auth or email verification later if needed.</p>
-              <Link
-                href="/"
-                className={cn(buttonVariants({ variant: "outline" }), "w-fit gap-2")}
+              <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 href="/" />}
               >
                 Back to home
-                <ArrowRight className="size-4" />
-              </Link>
-            </CardContent>
+                <ArrowRight data-icon="inline-end" />
+              </Button>
+            </CardFooter>
           </Card>
         </section>
       </div>

package/templates/modules/auth/nextjs/app/forgot-password/page.tsx

@@ -0,0 +1,11 @@
+import { ForgotPasswordForm } from "@/components/auth/forgot-password-form";
+
+export default 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/nextjs/app/reset-password/page.tsx

@@ -0,0 +1,17 @@
+import { Suspense } from "react";
+
+import { ResetPasswordForm } from "@/components/auth/reset-password-form";
+
+// A static page: the form reads the token from the URL in the browser, inside
+// <Suspense> as useSearchParams() requires
+export default function ResetPasswordPage() {
+  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">
+        <Suspense>
+          <ResetPasswordForm />
+        </Suspense>
+      </div>
+    </main>
+  );
+}