01criticalREADME→ README.md
Add install and Next.js quickstart to the top of README
The npm README has no install command, no sendMail example and no Next.js path. It opens with an EmailEngine pitch, then moves straight to troubleshooting. No run fetched any nodemailer docs run 115, so the README and training memory are all an agent has, and the README gives it nothing to copy. Resend wins because agents fetch a working Next.js recipe.
- README: 'See [nodemailer.com](https://nodemailer.com/) for documentation and terms.'
- README: '#### I have a different problem ... the best way to find help would be Stack Overflow'
- run 115: web_search(site.nodemailer.com ethereal createTestAccount sendMail getTestMessageUrl)
- run 115: fetched urls contain no nodemailer.com page
The fix
Put a 'Quick start (Next.js App Router)' section directly under the tagline, above the EmailEngine blockquote. Show install, one server-only transport helper that falls back to Ethereal when SMTP_URL is unset, and one server action. Move the troubleshooting FAQ below it.
Show proposed README.md · ready to paste
## Quick start (Next.js App Router)
```bash
npm install nodemailer server-only
```
Types are bundled. Do NOT install `@types/nodemailer`.
No account needed to try it: with `SMTP_URL` unset, Nodemailer creates a throwaway Ethereal inbox and gives you a preview URL.
```ts
// src/lib/mailer.ts
import 'server-only';
import nodemailer from 'nodemailer';
export async function getTransport() {
if (process.env.SMTP_URL) return nodemailer.createTransport(process.env.SMTP_URL);
const t = await nodemailer.createTestAccount(); // dev only
return nodemailer.createTransport({
host: t.smtp.host, port: t.smtp.port, secure: t.smtp.secure,
auth: { user: t.user, pass: t.pass }
});
}
```
```ts
// src/app/signup/actions.ts
'use server';
import nodemailer from 'nodemailer';
import { getTransport } from '@/lib/mailer';
export async function sendWelcome(to: string) {
const transport = await getTransport();
const info = await transport.sendMail({
from: process.env.EMAIL_FROM ?? 'App <no-reply@example.com>',
to,
subject: 'Welcome',
text: 'Thanks for signing up.',
html: '<p>Thanks for signing up.</p>'
});
return { id: info.messageId, preview: nodemailer.getTestMessageUrl(info) || null };
}
```
Real delivery: set `SMTP_URL=smtp://USER:PASS@HOST:587` (or `smtps://...:465`). Any SMTP provider works: Resend (`smtp.resend.com`, user `resend`, pass = API key), Amazon SES, Postmark, SendGrid, Mailgun, Gmail app password.
Rules: run on the Node.js runtime only (not Edge, not client components). `secure: true` only for port 465.