feat: document the Auth.js Email (magic link) provider + local email testing

Author: tsokolovsCreated Jul 27, 2026Updated Jul 27, 2026
Labels🌟 enhancement

Is your feature request related to a problem? Please describe.

The NextAuth.js documentation and scaffolded app talk about the Discord OAuth provider. The src/server/auth/config.ts file contains DiscordProvider and // ...add more providers here, and NextAuth.js usage docs contain instructions on Discord configuration, sessions, tRPC, DB adapters, and middleware — but not about the Email/magic link provider.

And that leaves an actual problem for everyone who would like to use a passwordless email sign-in:

  1. First, the Email provider is significantly different from OAuth providers – it needs a database adapter (for the VerificationToken model, which create-t3-app sets up upon choosing Prisma or Drizzle options) and an SMTP server to send the login links. And none of that is documented – people will have to exit the T3 docs and look it up from the Auth.js docs.
  2. Second, even after setting it up, there's no guidance on how to test it locally. People certainly don't want to send emails in development and while many other ecosystems contain a local SMTP server by default (Laravel Sail, Symfony, cookiecutter-django), there's no mention of an analogous workflow here. Most new users get stuck at "where do these emails actually go in dev?"

Describe the solution you'd like to see

  1. Adding the provider – a brief snippet with the addition of the Email provider of Auth.js to the providers array, mentioning that it needs a database adapter (which Prisma/Drizzle options are already providing, including the VerificationToken model) and the relevant .env / src/env.js files to configure SMTP settings.
  2. Testing email locally – a separate "Local email testing" section, where it's described how to change the SMTP settings of the provider to send email links to a local inbox during development, making magic-links to be sent locally instead of being really delivered. One can do this with any single-binary, MIT-licensed SMTP "catcher" with docker run command and no signup, e.g., Mailtrap Local.

This would follow the current docs style ("here's how to add another provider"), like in the Discord section, and would fill in some extra infrastructure.

Describe alternate solutions

  • Local-testing note only – skip the description of the provider itself and only provide the "test email locally" tip. It seems the provider setup is the hard part.
  • Leave it as-is – send people to the Auth.js docs and don't mention it at all. That's the current situation – it works, but SMTP requirement is exactly what makes T3-specific.

Additional information

I'm happy to make the PR if this is something you would like to see. Based on the contribution guidelines, I'm creating an issue first with a proposal.