@bernierllc/email-template-engine

Email template processing engine providing template compilation, variable substitution, base template composition, text version generation, and validation.

Installation

``bash
npm install @bernierllc/email-template-engine
`

Features

- ✅ Handlebars Template Compilation - Compile and render templates with variable substitution
- ✅ Base Template Composition - Combine header, content, and footer into complete emails
- ✅ Variable Extraction - Automatically extract and analyze template variables
- ✅ Text Version Generation - Convert HTML to plain text for email clients
- ✅ Template Validation - Syntax checking and error detection
- ✅ Custom Helpers - Extend with custom Handlebars helpers
- ✅ TypeScript Support - Full type definitions included
- ✅ Zero Dependencies on @bernierllc - Pure core package

Usage

$3

`typescript
import { EmailTemplateEngine } from '@bernierllc/email-template-engine';

const engine = new EmailTemplateEngine();

// Simple variable substitution
const result = engine.render(
'

Hello {{name}}!

',
{ name: 'John' }
);

console.log(result.data); // '

Hello John!

'
`

$3

`typescript
import { buildEmailTemplate } from '@bernierllc/email-template-engine';

const result = await buildEmailTemplate(
{
headerHtml: '

Company Logo

',
footerHtml: '',
},
'

{{title}}

{{message}}

',
{
title: 'Welcome',
message: 'Thank you for joining!',
}
);

console.log(result.data?.html); // Complete HTML email
console.log(result.data?.text); // Plain text version
`

$3

`typescript
import { extractTemplateVariables } from '@bernierllc/email-template-engine';

const template = '

{{title}}

{{user.name}}

';
const result = extractTemplateVariables(template);

console.log(result.data);
// [
// { name: 'title', path: 'title', type: 'string', occurrenceCount: 1, ... },
// { name: 'user', path: 'user.name', type: 'object', occurrenceCount: 1, ... }
// ]
`

$3

`typescript
import { validateEmailTemplate } from '@bernierllc/email-template-engine';

const result = validateEmailTemplate('

{{name}}

');

if (!result.data?.isValid) {
console.error('Validation errors:', result.data?.errors);
}
`

$3

`typescript
import { generateTextFromHtml } from '@bernierllc/email-template-engine';

const result = generateTextFromHtml(
'

Welcome

Check out our website

'
);

console.log(result.data);
// WELCOME
//
// Check out our website [https://example.com]
`

API Reference

$3

Main class for template processing.

#### Methods

##### compile(template: string, options?: CompilationOptions): TemplateResult

Compile a Handlebars template into a reusable function.

Options:
- strict - Throw on undefined variables (default: false)
- noEscape - Disable HTML escaping (default: false)
- helpers - Custom Handlebars helpers
- partials - Template partials

##### render(template: string, data: Record, options?: CompilationOptions): TemplateResult

Compile and render template with data in one step.

##### buildCompleteTemplate(baseTemplate: BaseTemplate, content: string, variables?: Record): Promise>

Build complete email by combining header, content, and footer.

Returns:
- html - Complete rendered HTML
- text - Plain text version
- variables - Extracted template variables
- metadata - Build metrics (time, variable count, content length)

##### generateTextVersion(html: string, options?: TextGenerationOptions): TemplateResult

Convert HTML to plain text.

Options:
- wordwrap - Wrap at N characters (default: 80)
- preserveNewlines - Keep line breaks (default: true)
- uppercaseHeadings - Uppercase headings (default: true)

##### extractVariables(template: string): TemplateResult

Extract all variables from template.

##### validateTemplate(template: string): TemplateResult

Validate template syntax and structure.

$3

All methods are available as standalone functions:

`typescript
import {
compileTemplate,
renderTemplate,
buildEmailTemplate,
generateTextFromHtml,
extractTemplateVariables,
validateEmailTemplate,
} from '@bernierllc/email-template-engine';
`

Default Helpers

Built-in Handlebars helpers included:

- formatDate - Format date objects
- uppercase - Convert string to uppercase
- lowercase - Convert string to lowercase

`typescript
const result = engine.render(
'

{{uppercase name}}

',
{ name: 'john' }
);
//

JOHN

`

Custom Helpers

Add your own Handlebars helpers:

`typescript
const engine = new EmailTemplateEngine();

const result = engine.render(
'

Price: {{currency amount}}

',
{ amount: 99.5 },
{
helpers: {
currency: (value: number) => $${value.toFixed(2)},
},
}
);
//

Price: $99.50

`

Error Handling

All methods return a TemplateResult object:

`typescript
const result = engine.render(template, data);

if (!result.success) {
console.error('Template error:', result.error);
return;
}

// Safe to use result.data
console.log(result.data);
`

Examples

$3

`typescript
const engine = new EmailTemplateEngine();

const welcomeTemplate =

Welcome to {{companyName}}

Hi {{userName}},

Your account email: {{email}}

Verify Account
;

const result = await engine.buildCompleteTemplate(
{
headerHtml: '',
footerHtml: '

',
},
welcomeTemplate,
{
companyName: 'ACME Corp',
userName: 'John Doe',
email: 'john@example.com',
verificationLink: 'https://example.com/verify/abc123',
}
);
`

$3

`typescript
const orderTemplate =

Order Confirmation

Order #{{orderNumber}}

Total: ${{total}}

{{#each items}}

• {{this.name}} - ${{this.price}}

{{/each}}

;

const result = await buildEmailTemplate(
baseTemplate,
orderTemplate,
{
orderNumber: '12345',
total: '99.99',
items: [
{ name: 'Product A', price: '49.99' },
{ name: 'Product B', price: '50.00' },
],
}
);
`

Integration Status

- Logger: Optional - Logs compilation errors and validation warnings when provided
- Docs-Suite: Ready - Complete API documentation with examples
- NeverHub: Optional - Publishes template processing events when available

$3

`typescript
import { EmailTemplateEngine } from '@bernierllc/email-template-engine';
import { Logger } from '@bernierllc/logger';

const logger = new Logger({ service: 'email-template-engine' });
const engine = new EmailTemplateEngine({ logger });

// Logger automatically logs:
// - Template compilation errors
// - Variable extraction issues
// - Text generation failures
`

Performance

- Template compilation: <10ms for typical email templates (5KB)
- Complete template building: <50ms including text generation
- Variable extraction: <5ms for templates with 50+ variables
- Compilation cache available for repeated use

TypeScript Support

Full TypeScript definitions included:

`typescript
import type {
BaseTemplate,
BuiltTemplate,
CompilationOptions,
TemplateResult,
TemplateValidationResult,
TemplateVariable,
TextGenerationOptions,
} from '@bernierllc/email-template-engine';
``

See Also

- @bernierllc/email-template-service - Template CRUD and provider sync
- @bernierllc/email-manager - Complete email management suite
- @bernierllc/logger - Optional logging integration

License

Copyright (c) 2025 Bernier LLC. All rights reserved.

This package is licensed under a limited-use license. See LICENSE file for details.