vintasend-react-email 0.9.1

package/README.md

@@ -0,0 +1,162 @@
+# vintasend-react-email
+
+React Email template renderer for VintaSend.
+
+This package provides a `BaseEmailTemplateRenderer` implementation that can:
+
+- load templates from file paths (`.js`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts`, `.cts`)
+- compile uncompiled TypeScript/TSX templates at runtime
+- render React body templates to HTML via `@react-email/render`
+- render templates from inline content (including loops, conditionals, and arbitrary logic)
+
+## Installation
+
+```bash
+npm install vintasend-react-email
+```
+
+## Exports
+
+- `ReactEmailTemplateRenderer`
+- `ReactEmailTemplateRendererFactory`
+
+## How it works
+
+### File-based templates (`render`)
+
+When VintaSend sends a notification, the renderer reads:
+
+- `notification.bodyTemplate`
+- `notification.subjectTemplate`
+
+Each file must export a function as either:
+
+- default export: `export default function Template(context) { ... }`
+- named export: `export function render(context) { ... }`
+
+The function receives the notification context and returns:
+
+- for **subject**: usually a string
+- for **body**: a React element or a string
+
+If body returns a React element, it is converted to HTML.
+
+### Inline templates (`renderFromTemplateContent`)
+
+Inline `templateContent.subject` and `templateContent.body` are compiled and executed at runtime.
+You can pass either:
+
+1. **Full module source** (with `export default` or `export function render`), or
+2. **Inline snippet**:
+    - function body (`const x = ...; if (...) ...; return ...;`)
+    - or expression (`<div>Hello</div>`, `'Subject text'`)
+
+This allows logic such as `if/else`, loops, mapping arrays, etc.
+
+## Usage
+
+### 1) Create renderer instance
+
+```ts
+import { ReactEmailTemplateRendererFactory } from 'vintasend-react-email';
+
+const templateRenderer = new ReactEmailTemplateRendererFactory<MyConfig>().create();
+```
+
+### 2) Use with your adapter (example)
+
+```ts
+// Example with an adapter that accepts a BaseEmailTemplateRenderer implementation
+const adapter = new SomeEmailAdapterFactory<MyConfig>().create(templateRenderer);
+```
+
+### 3) Template files
+
+`subject-template.ts`:
+
+```ts
+export default function SubjectTemplate(context: { name?: string }) {
+   return `Welcome ${context.name ?? ''}`;
+}
+```
+
+`body-template.tsx`:
+
+```tsx
+import React from 'react';
+
+export default function BodyTemplate(context: {
+   name?: string;
+   items?: string[];
+   isVip?: boolean;
+}) {
+   const items = context.items ?? [];
+
+   return (
+      <div>
+         <h1>Hello {context.name ?? ''}</h1>
+         {context.isVip ? <p>VIP user</p> : <p>Standard user</p>}
+         <ul>
+            {items.map((item, index) => (
+               <li key={index}>{item}</li>
+            ))}
+         </ul>
+      </div>
+   );
+}
+```
+
+## Inline content examples
+
+### Full module source
+
+```ts
+const templateContent = {
+   subject: `
+export default function Subject(context) {
+   return ` + '`' + `Welcome ${context.name ?? ''}` + '`' + `;
+}
+   `,
+   body: `
+import React from 'react';
+
+export default function Body(context) {
+   return <p>Hello {context.name ?? ''}</p>;
+}
+   `,
+};
+```
+
+### Snippet (function body)
+
+```ts
+const templateContent = {
+   subject: `
+const tier = context.isVip ? 'VIP' : 'User';
+return ` + '`' + `Welcome ${tier} ${context.name ?? ''}` + '`' + `;
+   `,
+   body: `
+const items = Array.isArray(context.items) ? context.items : [];
+return (
+   <ul>
+      {items.map((item, index) => (
+         <li key={index}>{String(item)}</li>
+      ))}
+   </ul>
+);
+   `,
+};
+```
+
+## Validation behavior
+
+- throws if `subjectTemplate` (file-based rendering) is missing
+- throws if `templateContent.subject` (inline rendering) is missing
+- throws if template file/content does not export a function
+
+## Development
+
+```bash
+npm test
+npm run build
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { ReactEmailTemplateRenderer, ReactEmailTemplateRendererFactory } from './react-email-template-renderer';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,iCAAiC,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { ReactEmailTemplateRenderer, ReactEmailTemplateRendererFactory } from './react-email-template-renderer';

package/dist/react-email-template-renderer.d.ts

@@ -0,0 +1,25 @@
+import type { BaseEmailTemplateRenderer, EmailTemplate, EmailTemplateContent } from 'vintasend/dist/services/notification-template-renderers/base-email-template-renderer';
+import type { JsonObject } from 'vintasend/dist/types/json-values';
+import type { BaseLogger } from 'vintasend/dist/services/loggers/base-logger';
+import type { AnyNotification, DatabaseNotification } from 'vintasend/dist/types/notification';
+import type { BaseNotificationTypeConfig } from 'vintasend/dist/types/notification-type-config';
+export declare class ReactEmailTemplateRenderer<Config extends BaseNotificationTypeConfig> implements BaseEmailTemplateRenderer<Config> {
+    private logger;
+    injectLogger(logger: BaseLogger): void;
+    render(notification: DatabaseNotification<Config>, context: JsonObject): Promise<EmailTemplate>;
+    renderFromTemplateContent(notification: AnyNotification<Config>, templateContent: EmailTemplateContent, context: JsonObject): Promise<EmailTemplate>;
+    private loadTemplateFactory;
+    private compileTemplateToCacheFile;
+    private compileSourceToCacheFile;
+    private loadTemplateFactoryFromContent;
+    private buildContentModuleSource;
+    private looksLikeTemplateModule;
+    private looksLikeFunctionBody;
+    private getEsbuildLoader;
+    private renderBodyOutput;
+    private renderSubjectOutput;
+}
+export declare class ReactEmailTemplateRendererFactory<Config extends BaseNotificationTypeConfig> {
+    create(): ReactEmailTemplateRenderer<Config>;
+}
+//# sourceMappingURL=react-email-template-renderer.d.ts.map

package/dist/react-email-template-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-email-template-renderer.d.ts","sourceRoot":"","sources":["../src/react-email-template-renderer.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,yBAAyB,EACzB,aAAa,EACb,oBAAoB,EACrB,MAAM,sFAAsF,CAAC;AAC9F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6CAA6C,CAAC;AAC9E,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC/F,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+CAA+C,CAAC;AAYhG,qBAAa,0BAA0B,CAAC,MAAM,SAAS,0BAA0B,CAC/E,YAAW,yBAAyB,CAAC,MAAM,CAAC;IAE5C,OAAO,CAAC,MAAM,CAA2B;IAEzC,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAIhC,MAAM,CACV,YAAY,EAAE,oBAAoB,CAAC,MAAM,CAAC,EAC1C,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,aAAa,CAAC;IAoBnB,yBAAyB,CAC7B,YAAY,EAAE,eAAe,CAAC,MAAM,CAAC,EACrC,eAAe,EAAE,oBAAoB,EACrC,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,aAAa,CAAC;YA0BX,mBAAmB;YAenB,0BAA0B;YAK1B,wBAAwB;YAyBxB,8BAA8B;IAiB5C,OAAO,CAAC,wBAAwB;IAmBhC,OAAO,CAAC,uBAAuB;IAI/B,OAAO,CAAC,qBAAqB;IAM7B,OAAO,CAAC,gBAAgB;YAQV,gBAAgB;IAQ9B,OAAO,CAAC,mBAAmB;CAO5B;AAED,qBAAa,iCAAiC,CAAC,MAAM,SAAS,0BAA0B;IACtF,MAAM;CAGP"}

package/dist/react-email-template-renderer.js

@@ -0,0 +1,135 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, extname, join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { pathToFileURL } from 'node:url';
+import { render as renderReactEmail } from '@react-email/render';
+import { transform } from 'esbuild';
+const TS_TEMPLATE_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts']);
+const COMPILED_TEMPLATE_CACHE_DIR = join(tmpdir(), 'vintasend-react-email-templates');
+export class ReactEmailTemplateRenderer {
+    constructor() {
+        this.logger = null;
+    }
+    injectLogger(logger) {
+        this.logger = logger;
+    }
+    async render(notification, context) {
+        this.logger?.info(`Rendering email template for notification ${notification.id}`);
+        const bodyTemplateFactory = await this.loadTemplateFactory(notification.bodyTemplate);
+        if (!notification.subjectTemplate) {
+            this.logger?.info('Subject template missing');
+            throw new Error('Subject template is required');
+        }
+        const subjectTemplateFactory = await this.loadTemplateFactory(notification.subjectTemplate);
+        const bodyOutput = await bodyTemplateFactory(context);
+        const subjectOutput = await subjectTemplateFactory(context);
+        return {
+            subject: this.renderSubjectOutput(subjectOutput),
+            body: await this.renderBodyOutput(bodyOutput),
+        };
+    }
+    async renderFromTemplateContent(notification, templateContent, context) {
+        this.logger?.info(`Rendering email template from content for notification ${notification.id}`);
+        if (!templateContent.subject) {
+            this.logger?.info('Subject template content missing');
+            throw new Error('Subject template is required');
+        }
+        const subjectTemplateFactory = await this.loadTemplateFactoryFromContent(templateContent.subject, 'subject');
+        const bodyTemplateFactory = await this.loadTemplateFactoryFromContent(templateContent.body, 'body');
+        const subjectOutput = await subjectTemplateFactory(context);
+        const bodyOutput = await bodyTemplateFactory(context);
+        return {
+            subject: this.renderSubjectOutput(subjectOutput),
+            body: await this.renderBodyOutput(bodyOutput),
+        };
+    }
+    async loadTemplateFactory(templatePath) {
+        const importPath = TS_TEMPLATE_EXTENSIONS.has(extname(templatePath).toLowerCase())
+            ? await this.compileTemplateToCacheFile(templatePath)
+            : templatePath;
+        const templateModule = (await import(pathToFileURL(importPath).href));
+        const templateExport = templateModule.default ?? templateModule.render;
+        if (typeof templateExport !== 'function') {
+            throw new Error(`Template at \"${templatePath}\" must export a function`);
+        }
+        return templateExport;
+    }
+    async compileTemplateToCacheFile(templatePath) {
+        const source = await readFile(templatePath, 'utf8');
+        return this.compileSourceToCacheFile(source, templatePath, this.getEsbuildLoader(templatePath));
+    }
+    async compileSourceToCacheFile(source, sourceIdentifier, loader) {
+        const sourceHash = createHash('sha1').update(`${sourceIdentifier}:${source}`).digest('hex');
+        const extension = extname(sourceIdentifier).replace('.', '') || loader;
+        const cacheFileName = `${sourceHash}-${extension}.mjs`;
+        const compiledPath = join(COMPILED_TEMPLATE_CACHE_DIR, cacheFileName);
+        await mkdir(dirname(compiledPath), { recursive: true });
+        const { code } = await transform(source, {
+            loader,
+            format: 'esm',
+            target: 'es2021',
+            jsx: 'automatic',
+            sourcefile: sourceIdentifier,
+            sourcemap: 'inline',
+        });
+        await writeFile(compiledPath, code, 'utf8');
+        return compiledPath;
+    }
+    async loadTemplateFactoryFromContent(templateContent, templateKind) {
+        const moduleSource = this.buildContentModuleSource(templateContent);
+        const contentIdentifier = `inline-${templateKind}-template.tsx`;
+        const compiledPath = await this.compileSourceToCacheFile(moduleSource, contentIdentifier, 'tsx');
+        const templateModule = (await import(pathToFileURL(compiledPath).href));
+        const templateExport = templateModule.default ?? templateModule.render;
+        if (typeof templateExport !== 'function') {
+            throw new Error(`${templateKind} template content must export a function`);
+        }
+        return templateExport;
+    }
+    buildContentModuleSource(templateContent) {
+        const trimmedContent = templateContent.trim();
+        if (this.looksLikeTemplateModule(trimmedContent)) {
+            return trimmedContent;
+        }
+        const functionBody = this.looksLikeFunctionBody(trimmedContent)
+            ? trimmedContent
+            : `return (${trimmedContent});`;
+        return [
+            'import React from "react";',
+            'export default function VintaSendTemplate(context) {',
+            functionBody,
+            '}',
+        ].join('\n');
+    }
+    looksLikeTemplateModule(templateContent) {
+        return /\bexport\s+default\b|\bexport\s+(const|function)\s+render\b/.test(templateContent);
+    }
+    looksLikeFunctionBody(templateContent) {
+        return /(^|\n)\s*(return\b|if\b|for\b|while\b|switch\b|const\b|let\b|var\b|throw\b|try\b)/.test(templateContent);
+    }
+    getEsbuildLoader(templatePath) {
+        const extension = extname(templatePath).toLowerCase();
+        if (extension === '.tsx') {
+            return 'tsx';
+        }
+        return 'ts';
+    }
+    async renderBodyOutput(output) {
+        if (typeof output === 'string') {
+            return output;
+        }
+        return renderReactEmail(output);
+    }
+    renderSubjectOutput(output) {
+        if (typeof output === 'string') {
+            return output;
+        }
+        return String(output ?? '');
+    }
+}
+export class ReactEmailTemplateRendererFactory {
+    create() {
+        return new ReactEmailTemplateRenderer();
+    }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "vintasend-react-email",
+  "version": "0.9.1",
+  "description": "VintaSend template renderer implementation for React Email",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "files": [
+    "dist"
+  ],
+  "author": "Hugo Bessa",
+  "license": "MIT",
+  "dependencies": {
+    "@react-email/render": "^2.0.4",
+    "esbuild": "^0.25.11",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "vintasend": "^0.9.1"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.0.18",
+    "typescript": "^5.9.3",
+    "vitest": "4.0.18"
+  }
+}