Vite plugin for email testing in development environments with mock SMTP server and HMR support
npm install @bernierllc/vite-email-testingVite plugin for email testing in development environments with mock SMTP server and HMR support.
- 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
``bash`
npm install --save-dev @bernierllc/vite-email-testing
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()
]
});
`
`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
}
})
]
});
`
The development UI is automatically available at http://localhost:5173/__email-testing (or your configured path).
- 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
The mock SMTP server automatically starts with your Vite dev server.
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.The plugin handles missing dependencies gracefully:
- Works without any @bernierllc dependencies
- SMTP server starts independently
- UI functions with minimal configuration
Copyright (c) 2025 Bernier LLC - See LICENSE.md
This package is part of the BernierLLC tools monorepo. See repository guidelines for contribution details.