better-ts-stack 2.1.2 → 2.2.0

package/templates/frontend/tanstack/src/routes/index.tsx.hbs

@@ -1,9 +1,16 @@
 import { createFileRoute{{#if useAuth}}, Link{{/if}} } from "@tanstack/react-router";
 import { ArrowRight } from "lucide-react";
 
-import { buttonVariants } from "~/components/ui/button";
-import { Card, CardContent, CardHeader, CardTitle } from "~/components/ui/card";
-import { cn } from "~/lib/utils";
+import { Alert, AlertDescription } from "~/components/ui/alert";
+import { Badge } from "~/components/ui/badge";
+import { Button } from "~/components/ui/button";
+import {
+  Card,
+  CardContent,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from "~/components/ui/card";
 
 export const Route = createFileRoute("/")({
   component: Home,
@@ -13,7 +20,7 @@ const featureList = [
   "TanStack Start SSR",
   "TanStack Router and Query",
   "React 19 and TypeScript",
-  "Tailwind CSS v4",
+  "Tailwind CSS v4 and shadcn/ui on Base UI",
   {{#if useAuth}}"Better Auth-ready session flow",{{/if}}
   {{#if (eq database "prisma")}}"Prisma database tooling",{{/if}}
   {{#if (eq database "drizzle")}}"Drizzle database tooling",{{/if}}
@@ -22,66 +29,74 @@ const featureList = [
 
 function Home() {
   return (
-    <main className="min-h-screen bg-background text-foreground">
-      <div className="mx-auto flex min-h-screen max-w-6xl flex-col justify-center gap-12 px-6 py-16 sm:px-10 lg:px-12">
+    <main className="min-h-svh">
+      <div className="mx-auto flex min-h-svh max-w-6xl flex-col justify-center gap-12 px-6 py-16 sm:px-10 lg:px-12">
         <section className="grid gap-10 lg:grid-cols-[1.2fr_0.8fr] lg:items-center">
-          <div className="space-y-6">
-            <span className="inline-flex w-fit items-center rounded-full border border-border bg-card px-3 py-1 text-xs font-medium uppercase tracking-[0.24em] text-muted-foreground shadow-sm">
-              Created with better-ts-stack
-            </span>
-            <div className="space-y-4">
+          <div className="flex flex-col gap-6">
+            <Badge variant="outline">Created with better-ts-stack</Badge>
+            <div className="flex flex-col gap-4">
               <h1 className="max-w-3xl text-4xl font-semibold tracking-tight sm:text-5xl">
                 Ship your stack faster with a polished TypeScript foundation.
               </h1>
               <p className="max-w-2xl text-base leading-7 text-muted-foreground sm:text-lg">
                 Your project already includes the core app shell, database wiring,
-                and a shadcn-compatible UI foundation so you can keep building
-                instead of setting up boilerplate.
+                and shadcn/ui components so you can keep building instead of
+                setting up boilerplate.
               </p>
             </div>
             <div className="flex flex-col gap-3 sm:flex-row">
               {{#if useAuth}}
-              <Link
-                to="/sign-up"
-                className={cn(buttonVariants({ size: "lg" }), "gap-2")}
-              >
+              <Button size="lg" nativeButton={false} render={<Link to="/sign-up" />}>
                 Create an account
-                <ArrowRight className="size-4" />
-              </Link>
-              <Link
-                to="/sign-in"
-                className={buttonVariants({ variant: "outline", size: "lg" })}
+                <ArrowRight data-icon="inline-end" />
+              </Button>
+              <Button
+                size="lg"
+                variant="outline"
+                nativeButton={false}
+                render={<Link to="/sign-in" />}
               >
                 Login
-              </Link>
+              </Button>
               {{else}}
-              <a
-                href="https://better-ts-stack.abdullahtech.me/docs"
-                target="_blank"
-                rel="noreferrer"
-                className={cn(buttonVariants({ size: "lg" }), "gap-2")}
+              <Button
+                size="lg"
+                nativeButton={false}
+                render={
+                  <a
+                    href="https://better-ts-stack.abdullahtech.me/docs"
+                    target="_blank"
+                    rel="noreferrer"
+                  />
+                }
               >
                 Explore the docs
-                <ArrowRight className="size-4" />
-              </a>
-              <a
-                href="https://tanstack.com/start/latest"
-                target="_blank"
-                rel="noreferrer"
-                className={buttonVariants({ variant: "outline", size: "lg" })}
+                <ArrowRight data-icon="inline-end" />
+              </Button>
+              <Button
+                size="lg"
+                variant="outline"
+                nativeButton={false}
+                render={
+                  <a
+                    href="https://tanstack.com/start/latest"
+                    target="_blank"
+                    rel="noreferrer"
+                  />
+                }
               >
                 TanStack guide
-              </a>
+              </Button>
               {{/if}}
             </div>
           </div>
 
-          <Card className="border-border bg-card shadow-sm">
+          <Card>
             <CardHeader>
               <CardTitle>Included in this starter</CardTitle>
             </CardHeader>
-            <CardContent className="space-y-4">
-              <ul className="space-y-3 text-sm text-muted-foreground">
+            <CardContent>
+              <ul className="flex flex-col gap-3 text-muted-foreground">
                 {featureList.map((feature) => (
                   <li key={feature} className="flex items-center gap-3">
                     <span className="size-2 rounded-full bg-primary" />
@@ -89,15 +104,19 @@ function Home() {
                   </li>
                 ))}
               </ul>
-              <div className="rounded-2xl border border-border bg-muted px-4 py-3 text-sm text-muted-foreground">
-                Start editing{" "}
-                <code className="font-mono">src/routes/index.tsx</code> and
-                shape the project around your product instead of setup chores.
-              </div>
             </CardContent>
+            <CardFooter>
+              <Alert>
+                <AlertDescription>
+                  Start editing{" "}
+                  <code className="font-mono">src/routes/index.tsx</code> and
+                  shape the project around your product instead of setup chores.
+                </AlertDescription>
+              </Alert>
+            </CardFooter>
           </Card>
         </section>
       </div>
     </main>
   );
-}
+}

package/templates/frontend/tanstack/src/styles/app.css

@@ -1,49 +1,95 @@
 @import "tailwindcss" source("../");
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+@import "@fontsource-variable/inter";
+
+@custom-variant dark (&:is(.dark *));
 
 @theme inline {
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --color-card: var(--card);
-  --color-card-foreground: var(--card-foreground);
-  --color-primary: var(--primary);
-  --color-primary-foreground: var(--primary-foreground);
-  --color-secondary: var(--secondary);
-  --color-secondary-foreground: var(--secondary-foreground);
-  --color-muted: var(--muted);
-  --color-muted-foreground: var(--muted-foreground);
-  --color-accent: var(--accent);
-  --color-accent-foreground: var(--accent-foreground);
-  --color-destructive: var(--destructive);
-  --color-border: var(--border);
-  --color-input: var(--input);
-  --color-ring: var(--ring);
+    --font-heading: var(--font-sans);
+    --font-sans: 'Inter Variable', sans-serif;
+    --color-sidebar-ring: var(--sidebar-ring);
+    --color-sidebar-border: var(--sidebar-border);
+    --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+    --color-sidebar-accent: var(--sidebar-accent);
+    --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+    --color-sidebar-primary: var(--sidebar-primary);
+    --color-sidebar-foreground: var(--sidebar-foreground);
+    --color-sidebar: var(--sidebar);
+    --color-chart-5: var(--chart-5);
+    --color-chart-4: var(--chart-4);
+    --color-chart-3: var(--chart-3);
+    --color-chart-2: var(--chart-2);
+    --color-chart-1: var(--chart-1);
+    --color-ring: var(--ring);
+    --color-input: var(--input);
+    --color-border: var(--border);
+    --color-destructive: var(--destructive);
+    --color-accent-foreground: var(--accent-foreground);
+    --color-accent: var(--accent);
+    --color-muted-foreground: var(--muted-foreground);
+    --color-muted: var(--muted);
+    --color-secondary-foreground: var(--secondary-foreground);
+    --color-secondary: var(--secondary);
+    --color-primary-foreground: var(--primary-foreground);
+    --color-primary: var(--primary);
+    --color-popover-foreground: var(--popover-foreground);
+    --color-popover: var(--popover);
+    --color-card-foreground: var(--card-foreground);
+    --color-card: var(--card);
+    --color-foreground: var(--foreground);
+    --color-background: var(--background);
+    --radius-sm: calc(var(--radius) * 0.6);
+    --radius-md: calc(var(--radius) * 0.8);
+    --radius-lg: var(--radius);
+    --radius-xl: calc(var(--radius) * 1.4);
+    --radius-2xl: calc(var(--radius) * 1.8);
+    --radius-3xl: calc(var(--radius) * 2.2);
+    --radius-4xl: calc(var(--radius) * 2.6);
 }
 
 :root {
-  --background: oklch(0.985 0 0);
-  --foreground: oklch(0.145 0 0);
-  --card: oklch(1 0 0);
-  --card-foreground: oklch(0.145 0 0);
-  --primary: oklch(0.205 0 0);
-  --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.97 0 0);
-  --secondary-foreground: oklch(0.205 0 0);
-  --muted: oklch(0.97 0 0);
-  --muted-foreground: oklch(0.556 0 0);
-  --accent: oklch(0.97 0 0);
-  --accent-foreground: oklch(0.205 0 0);
-  --destructive: oklch(0.577 0.245 27.325);
-  --border: oklch(0.922 0 0);
-  --input: oklch(0.922 0 0);
-  --ring: oklch(0.708 0 0);
+    --background: oklch(1 0 0);
+    --foreground: oklch(0.145 0 0);
+    --card: oklch(1 0 0);
+    --card-foreground: oklch(0.145 0 0);
+    --popover: oklch(1 0 0);
+    --popover-foreground: oklch(0.145 0 0);
+    --primary: oklch(0.205 0 0);
+    --primary-foreground: oklch(0.985 0 0);
+    --secondary: oklch(0.97 0 0);
+    --secondary-foreground: oklch(0.205 0 0);
+    --muted: oklch(0.97 0 0);
+    --muted-foreground: oklch(0.556 0 0);
+    --accent: oklch(0.97 0 0);
+    --accent-foreground: oklch(0.205 0 0);
+    --destructive: oklch(0.577 0.245 27.325);
+    --border: oklch(0.922 0 0);
+    --input: oklch(0.922 0 0);
+    --ring: oklch(0.708 0 0);
+    --chart-1: oklch(0.87 0 0);
+    --chart-2: oklch(0.556 0 0);
+    --chart-3: oklch(0.439 0 0);
+    --chart-4: oklch(0.371 0 0);
+    --chart-5: oklch(0.269 0 0);
+    --radius: 0.625rem;
+    --sidebar: oklch(0.985 0 0);
+    --sidebar-foreground: oklch(0.145 0 0);
+    --sidebar-primary: oklch(0.205 0 0);
+    --sidebar-primary-foreground: oklch(0.985 0 0);
+    --sidebar-accent: oklch(0.97 0 0);
+    --sidebar-accent-foreground: oklch(0.205 0 0);
+    --sidebar-border: oklch(0.922 0 0);
+    --sidebar-ring: oklch(0.708 0 0);
 }
 
-@media (prefers-color-scheme: dark) {
-  :root {
+.dark {
     --background: oklch(0.145 0 0);
     --foreground: oklch(0.985 0 0);
     --card: oklch(0.205 0 0);
     --card-foreground: oklch(0.985 0 0);
+    --popover: oklch(0.205 0 0);
+    --popover-foreground: oklch(0.985 0 0);
     --primary: oklch(0.922 0 0);
     --primary-foreground: oklch(0.205 0 0);
     --secondary: oklch(0.269 0 0);
@@ -56,30 +102,29 @@
     --border: oklch(1 0 0 / 10%);
     --input: oklch(1 0 0 / 15%);
     --ring: oklch(0.556 0 0);
-  }
-}
-
-@layer base {
-  *,
-  ::after,
-  ::before,
-  ::backdrop,
-  ::file-selector-button {
-    border-color: var(--color-gray-200, currentcolor);
-  }
+    --chart-1: oklch(0.87 0 0);
+    --chart-2: oklch(0.556 0 0);
+    --chart-3: oklch(0.439 0 0);
+    --chart-4: oklch(0.371 0 0);
+    --chart-5: oklch(0.269 0 0);
+    --sidebar: oklch(0.205 0 0);
+    --sidebar-foreground: oklch(0.985 0 0);
+    --sidebar-primary: oklch(0.488 0.243 264.376);
+    --sidebar-primary-foreground: oklch(0.985 0 0);
+    --sidebar-accent: oklch(0.269 0 0);
+    --sidebar-accent-foreground: oklch(0.985 0 0);
+    --sidebar-border: oklch(1 0 0 / 10%);
+    --sidebar-ring: oklch(0.556 0 0);
 }
 
 @layer base {
-  html {
-    color-scheme: light dark;
-  }
-
   * {
-    @apply border-gray-200 dark:border-gray-800;
-  }
-
-  html,
+    @apply border-border outline-ring/50;
+    }
   body {
-    @apply bg-gray-50 text-gray-900 dark:bg-gray-950 dark:text-gray-200;
-  }
+    @apply bg-background text-foreground;
+    }
+  html {
+    @apply font-sans;
+    }
 }

package/templates/modules/agents/AGENTS.md.hbs

@@ -11,10 +11,10 @@ Instructions for AI coding agents working in {{projectName}}. Read this before m
 - NestJS 12 REST API in TypeScript, using ES modules
 {{/if}}
 {{#if (eq framework 'nextjs')}}
-- Next.js 16 with the App Router, React 19, Tailwind CSS 4, and shadcn/ui
+- Next.js 16 with the App Router, React 19, Tailwind CSS 4, and shadcn/ui on Base UI
 {{/if}}
 {{#if (eq framework 'tanstack')}}
-- TanStack Start with Vite, Nitro, React 19, Tailwind CSS 4, and shadcn/ui
+- TanStack Start with Vite, Nitro, React 19, Tailwind CSS 4, and shadcn/ui on Base UI
 {{/if}}
 {{#if (eq database 'prisma')}}
 - PostgreSQL through Prisma 7
@@ -26,17 +26,12 @@ Instructions for AI coding agents working in {{projectName}}. Read this before m
 - MongoDB through Mongoose
 {{/if}}
 {{#if useAuth}}
+- Better Auth: email and password, email verification, password reset, and GitHub and Google sign-in when their keys are set. Emails go through Resend when `RESEND_API_KEY` is set and are printed to the log otherwise
 {{#if (eq framework 'express')}}
-- JWT auth: `POST /auth/register`, `POST /auth/login`, and `GET /auth/me`
+- Auth routes under `/api/auth` (`POST /api/auth/sign-up/email`, `POST /api/auth/sign-in/email`, ...). Clients without cookies send `Authorization: Bearer <token>`, using the `set-auth-token` header from sign-in
 {{/if}}
 {{#if (eq framework 'nestjs')}}
-- JWT auth: `POST /auth/register`, `POST /auth/login`, and `GET /auth/me`
-{{/if}}
-{{#if (eq framework 'nextjs')}}
-- Better Auth with email and password
-{{/if}}
-{{#if (eq framework 'tanstack')}}
-- Better Auth with email and password
+- Auth routes under `/api/auth` (`POST /api/auth/sign-up/email`, `POST /api/auth/sign-in/email`, ...). Clients without cookies send `Authorization: Bearer <token>`, using the `set-auth-token` header from sign-in
 {{/if}}
 {{/if}}
 {{#if useRateLimit}}
@@ -76,8 +71,9 @@ Run type-check and lint, and fix every error they report. Run the build too when
 - `src/env.ts`: checks the environment variables with Zod at startup, so a missing one stops the server with a clear message
 - `src/routes/`: one router per resource, mounted in `src/index.ts`
 {{#if useAuth}}
-- `src/controllers/`, `src/services/`: request handlers and data access for auth
-- `src/middleware/requireAuth.ts`: add it to a route to require a valid JWT
+- `src/lib/auth.ts`: the Better Auth server, mounted on `/api/auth` in `src/index.ts`
+- `src/lib/email.ts`: sends the verification and password reset emails
+- `src/middleware/requireAuth.ts`: add it to a route to require a session; `getSession(res)` returns it. `src/routes/me.ts` is an example
 {{/if}}
 {{#if useRateLimit}}
 - `src/middleware/rateLimit.ts`: the rate limiters
@@ -98,7 +94,8 @@ Run type-check and lint, and fix every error they report. Run the build too when
 - `src/env.ts`: checks the environment variables with Zod at startup, so a missing one stops the server with a clear message
 - `src/health/`: `GET /health`
 {{#if useAuth}}
-- `src/auth/`: the auth module. Put `@UseGuards(AuthGuard)` on a route to require a valid JWT
+- `src/auth/`: the Better Auth server (`auth.ts`), the emails it sends (`email.ts`), and the module that mounts it on `/api/auth` (`auth.module.ts`)
+- Every route needs a session unless it has `@AllowAnonymous()` (or `@OptionalAuth()`). Read the session with `@Session()`, as `src/me/me.controller.ts` does
 {{/if}}
 {{#if (eq database 'prisma')}}
 - `src/prisma/`: `PrismaService`, injected wherever the database is needed
@@ -112,10 +109,12 @@ Run type-check and lint, and fix every error they report. Run the build too when
 {{/if}}
 {{#if (eq framework 'nextjs')}}
 - `app/`: routes, layouts, and route handlers. Pages are Server Components unless they need state, effects, or event handlers
-- `components/ui/`: shadcn/ui components. Add new ones with the shadcn CLI instead of writing them by hand
+- `components/ui/`: shadcn/ui components built on Base UI (`@base-ui/react`). Add new ones with the shadcn CLI instead of writing them by hand. Use the `render` prop to change the rendered element, not Radix's `asChild`
 - `lib/utils.ts`: the `cn()` class name helper
+- `app/globals.css`: the shadcn theme. Style with its tokens (`bg-primary`, `text-muted-foreground`), not raw Tailwind colors, and space with `flex` + `gap-*`, not `space-y-*`
 {{#if useAuth}}
-- `lib/auth.ts`: the Better Auth server. `lib/auth-client.ts`: the client for components
+- `lib/auth.ts`: the Better Auth server. `lib/auth-client.ts`: the client for components. `lib/email.ts`: sends the verification and password reset emails
+- `lib/session.ts`: `getSession()` reads the session on the server, once per request
 - `app/api/auth/[...all]/route.ts`: the Better Auth endpoints. Do not rename it
 - `proxy.ts`: sends signed-out visitors from `/dashboard` to `/sign-in`. Add other protected paths to its `matcher`
 {{/if}}
@@ -133,10 +132,11 @@ Run type-check and lint, and fix every error they report. Run the build too when
 - `src/routes/`: file-based routes. A new file becomes a route
 - `src/routeTree.gen.ts`: generated by the dev server and the build. Never edit it
 - `src/router.tsx`, `src/routes/__root.tsx`: the router and the root layout
-- `src/components/ui/`: shadcn/ui components. Add new ones with the shadcn CLI instead of writing them by hand
+- `src/components/ui/`: shadcn/ui components built on Base UI (`@base-ui/react`). Add new ones with the shadcn CLI instead of writing them by hand. Use the `render` prop to change the rendered element, not Radix's `asChild`
 - `src/lib/utils.ts`: the `cn()` class name helper
+- `src/styles/app.css`: the shadcn theme. Style with its tokens (`bg-primary`, `text-muted-foreground`), not raw Tailwind colors, and space with `flex` + `gap-*`, not `space-y-*`
 {{#if useAuth}}
-- `src/lib/auth.ts`: the Better Auth server. `src/lib/auth-client.ts`: the client for components
+- `src/lib/auth.ts`: the Better Auth server. `src/lib/auth-client.ts`: the client for components. `src/lib/email.ts`: sends the verification and password reset emails
 - `src/routes/api/auth/$.ts`: the Better Auth endpoints. Do not rename it
 - `src/routes/dashboard.tsx`: an example of a protected route that redirects in `beforeLoad`
 {{/if}}
@@ -162,6 +162,12 @@ Run type-check and lint, and fix every error they report. Run the build too when
 - The Prisma client is generated into {{#if (eq framework 'express')}}`src/generated/`{{/if}}{{#if (eq framework 'nestjs')}}`src/generated/`{{/if}}{{#if (eq framework 'nextjs')}}`generated/`{{/if}}{{#if (eq framework 'tanstack')}}`generated/`{{/if}}. Never edit or commit it
 {{/if}}
 - Match the existing code style. ESLint settings are in `eslint.config.mjs`{{#if (eq framework 'express')}} and Prettier settings in `.prettierrc`{{/if}}{{#if (eq framework 'nestjs')}} and Prettier settings in `.prettierrc`{{/if}}
+{{#if (eq framework 'nextjs')}}
+- Write Tailwind classes in their canonical form. Use the theme utility when one exists (`rounded-4xl`, not `rounded-[2rem]`), and in an arbitrary value write `_` only where CSS needs a space, never after a comma: `bg-[linear-gradient(180deg,#f8fafc_0%,#eef2ff_100%)]`. The Tailwind CSS VS Code extension warns about the long forms
+{{/if}}
+{{#if (eq framework 'tanstack')}}
+- Write Tailwind classes in their canonical form. Use the theme utility when one exists (`rounded-4xl`, not `rounded-[2rem]`), and in an arbitrary value write `_` only where CSS needs a space, never after a comma: `bg-[linear-gradient(180deg,#f8fafc_0%,#eef2ff_100%)]`. The Tailwind CSS VS Code extension warns about the long forms
+{{/if}}
 - Add a dependency only when the task needs it, and install it with {{packageManager}}
 
 ## Production rules
@@ -178,6 +184,7 @@ Run type-check and lint, and fix every error they report. Run the build too when
 - Keep the security setup in `src/main.ts` and `src/app.module.ts` in place. Set `CORS_ORIGIN` to your real origins in production
 {{/if}}
 {{#if (eq framework 'nextjs')}}
+- Server first: do not `await` data at the top of a page or layout, which holds back the whole page. Move each `await` into the component that needs the data and wrap that component in `<Suspense>` with a fallback, so the rest of the page is sent at once{{#if useAuth}}. `app/dashboard/page.tsx` shows the pattern with `getSession()`{{/if}}
 - Code that reads secrets or the database stays on the server. Only variables prefixed with `NEXT_PUBLIC_` reach the browser, so never put a secret in one
 {{/if}}
 {{#if (eq framework 'tanstack')}}
@@ -192,6 +199,9 @@ Run type-check and lint, and fix every error they report. Run the build too when
 {{/if}}
 {{/if}}
 {{#if (eq framework 'express')}}
+{{#if useAuth}}
+- Check the session on the server in every protected route with `requireAuth`
+{{/if}}
 - Keep `GET /health` fast and free of auth{{#if useRateLimit}} and rate limiting{{/if}}, so hosts can check that the app is up
 {{/if}}
 {{#if (eq framework 'nestjs')}}
@@ -225,11 +235,9 @@ The libraries here may be newer than what you know. When you are not sure how an
 - Mongoose: https://mongoosejs.com/docs
 {{/if}}
 {{#if useAuth}}
-{{#if (eq framework 'nextjs')}}
-- Better Auth: https://www.better-auth.com/docs
-{{/if}}
-{{#if (eq framework 'tanstack')}}
 - Better Auth: https://www.better-auth.com/docs
+{{#if (eq framework 'nestjs')}}
+- NestJS Better Auth integration: https://github.com/ThallesP/nestjs-better-auth
 {{/if}}
 {{/if}}
 - Zod: https://zod.dev

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

@@ -1,20 +1,21 @@
 {
   "id": "auth",
-  "name": "JWT Auth",
-  "description": "JWT authentication with bcrypt password hashing",
+  "name": "Better Auth",
+  "description": "Better Auth for Express: 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"
+    "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/express/src/lib/auth.ts.hbs

@@ -0,0 +1,143 @@
+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";
+import { MongoClient } from "mongodb";
+{{/if}}
+import { bearer } from "better-auth/plugins";
+
+import { env } from "../env";
+{{#if (eq database 'drizzle')}}
+import { db } from "./db";
+{{/if}}
+import { sendEmail } from "./email";
+{{#if (eq database 'prisma')}}
+import { prisma } from "./prisma";
+{{/if}}
+
+{{#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}}
+{{#if (eq database 'mongoose')}}
+// Better Auth talks to MongoDB through the driver, next to Mongoose
+export const mongoClient = new MongoClient(env.MONGODB_URI);
+
+{{/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();
+}
+
+export const auth = 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(mongoClient.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 by the server from req.ip on every request (see index.ts)
+    ipAddress: { ipAddressHeaders: ["x-client-ip"] },
+  },
+});
+
+export type Session = typeof auth.$Infer.Session;