Added smtp email support and email verification for user auth (#52)

* Add email functionality with Nodemailer configuration

- Integrated Nodemailer for sending emails with a configurable SMTP transport
- Added email-related environment variables to .env.example
- Created email action and library for sending emails
- Included TypeScript types for Nodemailer
- Configured email sending with Resend as the SMTP provider

* Update README with Email Configuration and Usage Guide

- Added comprehensive email configuration section to README
- Included environment variables for SMTP email settings
- Documented email sending methods (form actions and programmatic)
- Provided recommended email service providers
- Enhanced documentation for email functionality in the project

* Add welcome email to sign-up process

- Integrated email sending functionality in the sign-up handler
- Send a welcome email to new users upon successful registration
- Imported sendEmail utility from the email library
- Configured a simple welcome message for new sign-ups

* Add bot prevention mechanism to sign-up process

- Implemented a honeypot field in the sign-up form to prevent bot registrations
- Added middleware validation in the auth action to reject sign-ups with the honeypot field
- Introduced a hidden input field in the sign-up page to catch automated bot submissions

* Implement email verification flow

- Added email verification configuration in auth library
- Created a new verify-email page for unverified users
- Updated dashboard to redirect unverified users to email verification
- Modified Verification table to include updatedAt column
- Removed manual email sending from sign-up action

* Update sign-out redirect to sign-in page

* Add configurable email verification toggle

- Added BETTER_AUTH_EMAIL_VERIFICATION environment variable
- Updated .env.example with new configuration option
- Modified auth library to conditionally send email verification
- Updated dashboard to respect email verification configuration
- Simplified README email provider recommendations

* Update README tip formatting

* Simplify README email usage documentation

* rm email action

* updated package version

Author: cameronapak

.env.example

@@ -5,3 +5,12 @@ ASTRO_DB_APP_TOKEN=""
 # Better Auth (required) - https://www.better-auth.com/docs/installation#set-environment-variables
 BETTER_AUTH_SECRET=""
 BETTER_AUTH_URL="http://localhost:4321"
+BETTER_AUTH_EMAIL_VERIFICATION="false"
+
+# Mail server configuration
+MAIL_HOST=smtp.resend.com
+MAIL_PORT=465
+MAIL_SECURE=true
+MAIL_AUTH_USER=resend
+MAIL_AUTH_PASS=your_resend_api_key
+MAIL_FROM=your_verified_sender@yourdomain.com

README.md

@@ -2,7 +2,7 @@
 
 A modern, type-safe web development stack using Astro, TypeScript, HTMX, Alpine.js, and more.
 
-> [!TIP] 💡
+> [!TIP]
 > [Turso](https://tur.so/freedomstack) has a generous free tier for database hosting and management. And, when it's time to scale, use the code `FREEDOMSTACK` for a discount on paid plans.
 
 ## Get Started 🚀
@@ -39,6 +39,14 @@ ASTRO_DB_APP_TOKEN=""     # Added by npm run db:setup
 # Better Auth (required)
 BETTER_AUTH_SECRET=""     # Auto-generated during setup
 BETTER_AUTH_URL="http://localhost:4321"
+
+# Email Configuration (optional) - For sending emails
+MAIL_HOST=""             # SMTP host (e.g., smtp.resend.com)
+MAIL_PORT=""             # SMTP port (e.g., 465)
+MAIL_SECURE=""          # Use TLS/SSL (true/false)
+MAIL_AUTH_USER=""       # SMTP username
+MAIL_AUTH_PASS=""       # SMTP password or API key
+MAIL_FROM=""            # Sender email address
 ```
 
 ### 3. Have fun!
@@ -139,6 +147,42 @@ npm run host:deploy
 
 ---
 
+## Send Emails
+
+## Email Configuration 📧
+
+Freedom Stack includes a pre-configured email service using Nodemailer. This allows you to:
+
+- Send transactional emails
+- Use any SMTP provider
+- Handle email templates
+- Maintain type safety
+
+### Setting up Email
+
+1. Configure your environment variables as shown above
+
+Send emails programmatically:
+
+```typescript
+import { sendEmail } from "@/lib/email";
+
+await sendEmail({
+  to: "recipient@example.com",
+  subject: "Hello!",
+  html: "<h1>Welcome!</h1>"
+});
+```
+
+### Email Providers
+
+While you can use any SMTP provider, we recommend [Resend](https://resend.com) - Modern email API with generous free tier.
+
+> [!TIP]
+> Resend offers 100 emails/day free and has excellent developer experience.
+
+---
+
 ## Vision ❤️
 
 I dream of a lightweight, simple web development stack that invokes a fun web

db/config.ts

@@ -62,7 +62,8 @@ const Verification = defineTable({
     identifier: column.text(),
     value: column.text(),
     expiresAt: column.date(),
-    createdAt: column.date()
+    createdAt: column.date(),
+    updatedAt: column.date()
   }
 });
 

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "create-freedom-stack",
   "type": "module",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "description": "Create a new Freedom Stack project - A modern, type-safe web development stack using Astro, TypeScript, HTMX, Alpine.js, and more",
   "author": "Cameron Pak",
   "license": "MIT",
@@ -66,6 +66,7 @@
     "@astrojs/tailwind": "^5.1.5",
     "@iconify-json/lucide": "^1.2.24",
     "@iconify-json/lucide-lab": "^1.2.3",
+    "@types/nodemailer": "^6.4.17",
     "alpinejs": "^3.14.8",
     "astro": "^5.1.9",
     "astro-iconify": "^1.2.0",
@@ -77,6 +78,7 @@
     "htmx.org": "2.0.1",
     "isomorphic-dompurify": "^2.20.0",
     "marked": "^15.0.6",
+    "nodemailer": "^6.10.0",
     "ora": "^8.1.1",
     "trix": "^2.1.12"
   },

package.json

@@ -53,10 +53,18 @@ export const auth = {
       email: z.string().email(),
       password: z.string(),
       name: z.string(),
-      imageUrl: z.string().optional()
+      imageUrl: z.string().optional(),
+      middleware: z.string().optional()
     }),
-    handler: async (input, context) =>
-      await handleAuthResponse(
+    handler: async (input, context) => {
+      if (input.middleware) {
+        throw new ActionError({
+          code: "BAD_REQUEST",
+          message: "Bots are not allowed to sign up"
+        });
+      }
+
+      return await handleAuthResponse(
         () =>
           betterAuth.api.signUpEmail({
             body: { ...input, image: input.imageUrl || "" },
@@ -65,7 +73,8 @@ export const auth = {
           }),
         context,
         "BAD_REQUEST"
-      )
+      );
+    }
   }),
 
   signIn: defineAction({

src/actions/auth.ts

@@ -28,6 +28,20 @@ interface ImportMetaEnv {
   readonly BETTER_AUTH_URL: string;
   /** https://better-auth.com/ */
   readonly BETTER_AUTH_SECRET: string;
+  /** Toggle on email verification */
+  readonly BETTER_AUTH_EMAIL_VERIFICATION: "true" | "false";
+  /** Mail server host */
+  readonly MAIL_HOST: string;
+  /** Mail server port */
+  readonly MAIL_PORT: string;
+  /** Mail server secure setting */
+  readonly MAIL_SECURE: string;
+  /** Mail server auth user */
+  readonly MAIL_AUTH_USER: string;
+  /** Mail server auth password */
+  readonly MAIL_AUTH_PASS: string;
+  /** Email address to send from */
+  readonly MAIL_FROM: string;
 }
 
 interface ImportMeta {

src/env.d.ts

@@ -1,6 +1,7 @@
 import { betterAuth } from "better-auth";
 import { Account, db, Session, User, Verification } from "astro:db";
 import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { sendEmail } from "@/lib/email";
 
 export const auth = betterAuth({
   baseURL: import.meta.env.BETTER_AUTH_URL,
@@ -19,6 +20,18 @@ export const auth = betterAuth({
     },
     provider: "sqlite"
   }),
+  emailVerification: {
+    sendOnSignUp: import.meta.env.BETTER_AUTH_EMAIL_VERIFICATION === "true",
+    sendVerificationEmail: async ({ user, url, token }, request) => {
+      const updatedUrl = new URL(url);
+      updatedUrl.searchParams.set("callbackURL", "/sign-out");
+      await sendEmail({
+        to: user.email,
+        subject: "Verify your email address",
+        html: `<a href="${updatedUrl}">Click the link to verify your email</a>`
+      });
+    }
+  },
   emailAndPassword: {
     enabled: true
   },

src/lib/auth.ts

@@ -0,0 +1,64 @@
+/**
+ * Adapted from: https://developers.netlify.com/guides/send-emails-with-astro-and-resend/
+ */
+import { createTransport, type Transporter } from "nodemailer";
+
+type SendEmailOptions = {
+  /** Email address of the recipient */
+  to: string;
+  /** Subject line of the email */
+  subject: string;
+  /** Message used for the body of the email */
+  html: string;
+};
+
+// Singleton instance
+let transporter: Transporter | null = null;
+
+async function getEmailTransporter(): Promise<Transporter> {
+  // Return existing transporter if already initialized
+  if (transporter) {
+    return transporter;
+  }
+
+  const requiredEnvVars = ["MAIL_HOST", "MAIL_PORT", "MAIL_SECURE", "MAIL_AUTH_USER", "MAIL_AUTH_PASS", "MAIL_FROM"];
+
+  const missingEnvVars = requiredEnvVars.filter((envVar) => !import.meta.env[envVar]);
+
+  if (missingEnvVars.length > 0) {
+    throw new Error(`Missing mail configuration: ${missingEnvVars.join(", ")}`);
+  }
+
+  // Create new transporter if none exists
+  transporter = createTransport({
+    host: import.meta.env.MAIL_HOST,
+    port: parseInt(import.meta.env.MAIL_PORT),
+    secure: import.meta.env.MAIL_SECURE === "true",
+    auth: {
+      user: import.meta.env.MAIL_AUTH_USER,
+      pass: import.meta.env.MAIL_AUTH_PASS
+    }
+  });
+
+  return transporter;
+}
+
+export async function sendEmail(options: SendEmailOptions): Promise<Transporter> {
+  const emailTransporter = await getEmailTransporter();
+  return new Promise(async (resolve, reject) => {
+    // Build the email message
+    const { to, subject, html } = options;
+    const from = import.meta.env.MAIL_FROM;
+    const message = { to, subject, html, from };
+
+    // Send the email
+    emailTransporter.sendMail(message, (err, info) => {
+      if (err) {
+        console.error(err);
+        reject(err);
+      }
+      console.log("Message sent:", info.messageId);
+      resolve(info);
+    });
+  });
+}

src/lib/email.ts

@@ -12,9 +12,6 @@ export const onRequest = defineMiddleware(async (context, next) => {
   } else {
     context.locals.user = null;
     context.locals.session = null;
-    if (context.url.pathname === "/sign-out") {
-      return context.redirect("/");
-    }
   }
 
   return next();

src/middleware.ts

@@ -10,10 +10,12 @@ if (!Astro.locals.session) {
   return Astro.redirect("/sign-in");
 }
 
-const user = Astro.locals.user as { email: string };
+const user = Astro.locals.user;
 
 if (!user) {
   return Astro.redirect("/sign-in");
+} else if (!user.emailVerified && import.meta.env.BETTER_AUTH_EMAIL_VERIFICATION === "true") {
+  return Astro.redirect("/verify-email");
 }
 
 const allPosts = await db.select().from(Posts).where(eq(Posts.author, user.email)).orderBy(desc(Posts.pubDate));

src/pages/dashboard/index.astro

@@ -8,5 +8,5 @@ if (result?.data?.success) {
   setAuthCookiesFromResponse(result.data.cookiesToSet, Astro.cookies);
 }
 
-return Astro.redirect("/");
+return Astro.redirect("/sign-in");
 ---

src/pages/sign-out.astro

@@ -60,6 +60,8 @@ if (result?.data?.success) {
             placeholder="email@example.com"
           />
         </label>
+        {/* Honeypot field to prevent bots from signing up */}
+        <input type="hidden" name="middleware" />
         <label class="form-control w-full">
           <div class="label">
             <span class="label-text">Password</span>

src/pages/sign-up.astro

@@ -0,0 +1,25 @@
+---
+import Layout from "@/layouts/Layout.astro";
+import Container from "@sections/Container.astro";
+import Navbar from "@sections/Navbar.astro";
+import Footer from "@sections/Footer.astro";
+
+const user = Astro.locals.user;
+
+if (!user) {
+  return Astro.redirect("/sign-in");
+}
+
+const email = user?.email;
+---
+
+<Layout title="Verify Email">
+  <Navbar title="Freedom Stack" sticky links={[{ text: "Home", href: "/" }]} />
+  <Container align="center">
+    <div class="bg-white p-6 rounded-xl border-2 border-slate-200 flex flex-col gap-4 max-w-sm w-full">
+      <h1>Verify Your Email</h1>
+      <p class="text-slate-600">Please click the link in your email ({email}) to verify your account.</p>
+    </div>
+  </Container>
+  <Footer />
+</Layout>