@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

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

Usage

Basic Setup

Add the plugin to your vite.config.ts:

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

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

Configuration

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).

Features

• 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.

Sending Emails

Configure your application to send emails to the mock server:

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

await transporter.sendMail({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Test Email',
  html: '<p>This is a test email</p>'
});

Template Hot Reloading

The plugin watches template files and triggers HMR updates:

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

Plugin Options

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

SMTPConfig

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

UIConfig

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

TemplateConfig

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

Use Cases

Email Development

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

Integration Testing

Test email functionality without external services:

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

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

Email Template Testing

Test different email templates with various data:

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

Advanced Usage

Programmatic Access

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();

Custom Template Watcher

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

SMTP Server Won't Start

Check if port is already in use:

lsof -i :2525

Change port in configuration:

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

Template Changes Not Detected

Verify template directory exists and has correct path:

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

UI Not Loading

Check Vite dev server is running and visit correct URL:

http://localhost:5173/__email-testing

Integration Documentation

Logger Integration

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:

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

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

NeverHub Integration

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.

Graceful Degradation

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.