@bernierllc/vite-email-testing

Vite plugin for email testing in development environments with mock SMTP server and HMR support.

Features

- Mock SMTP Server: Auto-start SMTP server during development
- Email Capture: Capture all emails sent during development
- Development UI: Web interface for viewing captured emails
- Hot Module Replacement: HMR support for email template changes
- Template Watching: Automatic recompilation on template changes
- Zero Configuration: Works out of the box with sensible defaults

Installation

``bash
npm install --save-dev @bernierllc/vite-email-testing
`

Usage

$3

Add the plugin to your vite.config.ts:

`typescript
import { defineConfig } from 'vite';
import { emailTesting } from '@bernierllc/vite-email-testing';

export default defineConfig({
plugins: [
emailTesting()
]
});
`

$3

`typescript
import { defineConfig } from 'vite';
import { emailTesting } from '@bernierllc/vite-email-testing';

export default defineConfig({
plugins: [
emailTesting({
// SMTP server configuration
smtp: {
port: 2525,
host: 'localhost'
},

// Development UI configuration
ui: {
port: 3001,
path: '/__email-testing',
autoOpen: true
},

// Template watching
templates: {
dir: './src/templates',
extensions: ['.html', '.liquid', '.hbs'],
hotReload: true
}
})
]
});
`

Development UI

The development UI is automatically available at http://localhost:5173/__email-testing (or your configured path).

$3

- Email List: View all captured emails
- Email Detail: Full email preview with HTML rendering
- Search & Filter: Find specific emails
- Clear Emails: Delete individual or all emails
- Real-time Updates: Auto-refreshes when new emails arrive

SMTP Server

The mock SMTP server automatically starts with your Vite dev server.

$3

Configure your application to send emails to the mock server:

`typescript
const transporter = nodemailer.createTransport({
host: 'localhost',
port: 2525,
secure: false
});

await transporter.sendMail({
from: 'sender@example.com',
to: 'recipient@example.com',
subject: 'Test Email',
html: '

This is a test email

'
});
`

Template Hot Reloading

The plugin watches template files and triggers HMR updates:

`typescript
emailTesting({
templates: {
dir: './src/templates',
extensions: ['.html', '.liquid', '.hbs'],
hotReload: true
}
})
`

When a template file changes:
1. File change is detected
2. Template is recompiled
3. Browser is notified via WebSocket
4. Preview is automatically updated

API

$3

`typescript
interface EmailTestingOptions {
smtp?: SMTPConfig;
ui?: UIConfig;
templates?: TemplateConfig;
preview?: PreviewConfig;
}
`

#### SMTPConfig

`typescript
interface SMTPConfig {
port?: number; // Default: 2525
host?: string; // Default: 'localhost'
secure?: boolean; // Default: false
authOptional?: boolean; // Default: true
}
`

#### UIConfig

`typescript
interface UIConfig {
port?: number; // Default: 3001
path?: string; // Default: '/__email-testing'
autoOpen?: boolean; // Default: false
cors?: boolean; // Default: true
}
`

#### TemplateConfig

`typescript
interface TemplateConfig {
dir?: string; // Default: './src/templates'
extensions?: string[]; // Default: ['.html', '.liquid', '.hbs']
hotReload?: boolean; // Default: true
excludePatterns?: string[]; // Default: ['/node_modules/']
}
`

Use Cases

$3

Perfect for developing email templates with instant feedback:

1. Start Vite dev server
2. Edit email templates
3. Send test emails
4. View results instantly in UI
5. Iterate quickly with HMR

$3

Test email functionality without external services:

`typescript
// Send email in your code
await sendWelcomeEmail(user);

// Check in development UI
// Navigate to http://localhost:5173/__email-testing
// Verify email was sent correctly
`

$3

Test different email templates with various data:

`typescript
// templates/welcome.html changes automatically reload
// Test with different data sets
// Preview responsive layouts
`

Advanced Usage

$3

`typescript
import { MockSMTPServer } from '@bernierllc/vite-email-testing';

const server = new MockSMTPServer({ port: 2525 });
await server.start();

server.on('email', (email) => {
console.log('Email captured:', email.subject);
});

const emails = server.getCapturedEmails();
`

$3

`typescript
import { TemplateWatcher } from '@bernierllc/vite-email-testing';

const watcher = new TemplateWatcher({
dir: './my-templates',
extensions: ['.html', '.ejs']
});

watcher.on('change', (change) => {
console.log('Template changed:', change.path);
});

watcher.start();
`

Browser Support

Works with all modern browsers that support:
- WebSocket (for HMR)
- ES6+ JavaScript
- Fetch API

Performance

- Minimal overhead in development
- Auto-cleanup on server shutdown
- Efficient file watching with debouncing
- Lightweight UI with no external dependencies

Security

Note: This package is for development only. Never use in production.

- No authentication required
- SMTP server accepts all connections
- UI accessible without credentials
- Not designed for security-sensitive environments

Troubleshooting

$3

Check if port is already in use:

`bash
lsof -i :2525
`

Change port in configuration:

`typescript
emailTesting({
smtp: { port: 3000 }
})
`

$3

Verify template directory exists and has correct path:

`typescript
emailTesting({
templates: {
dir: './src/email-templates', // Absolute or relative to project root
hotReload: true
}
})
`

$3

Check Vite dev server is running and visit correct URL:

`
http://localhost:5173/__email-testing
`

Integration Documentation

$3

This package is a development tool for email testing and does not require logger integration since:
- All logging is console-based for development visibility
- No production logging requirements apply
- Logs are meant for developer debugging during Vite development

If you need structured logging, you can manually integrate @bernierllc/logger:

`typescript
import { detectLogger } from '@bernierllc/logger';

// Optional logger detection for your application
const logger = detectLogger();
`

$3

This package does not include NeverHub integration as it's a development-only tool:
- Not intended for production deployment
- No server-side persistence needed
- Emails are stored in memory during development

For production email handling, consider using @bernierllc/email-service` which includes full NeverHub integration.

$3

The plugin handles missing dependencies gracefully:
- Works without any @bernierllc dependencies
- SMTP server starts independently
- UI functions with minimal configuration

License

Copyright (c) 2025 Bernier LLC - See LICENSE.md

Contributing

This package is part of the BernierLLC tools monorepo. See repository guidelines for contribution details.