Auth Magic Link Sending

[adityapat24]

Goal

When a user submits their email on the sign-in form, they receive a real magic-link email. Clicking the link signs them in and creates a session in Mongo.

Tasks

Configure the Nodemailer transport

• Open src/lib/auth/config.ts and locate the EmailProvider configuration object.
  • What this accomplishes: This is the section of NextAuth's config that controls magic-link auth. Currently it's a stub.
• Set the server field to a real Nodemailer transport built from the env vars EMAIL_SERVER_HOST, EMAIL_SERVER_PORT, EMAIL_SERVER_USER, EMAIL_SERVER_PASSWORD.
  • What this accomplishes: Tells NextAuth where to send the magic-link emails from. Without this, submitting the sign-in form does nothing.
• Set the from field to the value of EMAIL_FROM env var.
  • What this accomplishes: This is the sender address the recipient sees in their inbox. Should be something like registration@hackbeanpot.com.
• Verify all five env vars are present in .env.example and have real values in local .env. If .env.example is missing any, add them.
  • What this accomplishes: Future devs setting up the project know exactly which SMTP variables to provide.

Verify the existing Mailgun setup

• Send a test email through the configured Mailgun transport and confirm it arrives in a real inbox.
  • What this accomplishes: Proves the existing env vars and Mailgun account are actually working before integrating into NextAuth. Catches setup issues at the simplest layer.

Customize the email template

• Override NextAuth's default email template by providing a sendVerificationRequest function on the EmailProvider.
  • What this accomplishes: Replaces NextAuth's generic default email with a HackBeanpot-branded one. Default templates look spammy.
• Write an HTML email body that includes the HackBeanpot logo (or just the wordmark if no logo asset is available), a one-line explanation ("Click the button below to sign in to the HackBeanpot application portal"), a big call-to-action button containing the magic link, and a fallback plaintext link.
  • What this accomplishes: Recipients trust the email is legitimate, the action is clear, and the button works even when images are blocked.
• Write a plaintext version of the same email for clients that don't render HTML.
  • What this accomplishes: Email best practice — improves deliverability and works in text-only clients.
• Make sure the link in the email is the one NextAuth provides (url parameter to sendVerificationRequest), not a hardcoded URL.
  • What this accomplishes: Each link is a unique signed token. Hardcoding a URL would break the sign-in flow entirely.

Verify Mongo adapter is creating the right collections

• Sign in once with a fresh email address against a clean local database.
  • What this accomplishes: Triggers the adapter to create its collections on first use.
• Inspect the database and confirm these four collections exist with at least one document each: users, accounts, sessions, verification_tokens.
  • What this accomplishes: Proves the Mongo adapter is configured correctly. If any are missing or empty, the adapter setup in src/lib/auth/adapter.ts is wrong.
• Confirm the users document has the email address you signed in with.
  • What this accomplishes: Sanity check that the user record is being populated, not just created empty.

End-to-end test

• From a freshly-cloned repo state with an empty database, run through the full flow: load /auth/signin, enter an email, submit, open your real inbox), click the link in the email, confirm you land somewhere as a signed-in user.
  • What this accomplishes: Proves every piece works together. The most common failure mode is having one piece work in isolation but not the full chain.
• Test the failure cases: expired token (wait 10 min and click the link), reused token (click the same link twice), malformed token (truncate the URL).
  • What this accomplishes: Confirms NextAuth's built-in protections are active and the user sees the right error page rather than a crash.

Definition of done

• Submitting the sign-in form sends a real email to the address provided.
• Clicking the magic link successfully signs the user in.
• All four NextAuth collections appear in Mongo with correct documents.
• The email body looks like a HackBeanpot email, not a default template.
• Failure cases (expired/reused/malformed token) display a sensible error.