vintasend-react-email 0.9.1 → 0.10.0

package/README.md

@@ -19,6 +19,40 @@ npm install vintasend-react-email
 
 - `ReactEmailTemplateRenderer`
 - `ReactEmailTemplateRendererFactory`
+- `ReactEmailInlineTemplateRenderer`
+- `ReactEmailInlineTemplateRendererFactory`
+
+## Template compilation script
+
+For environments that can only deploy a single source file (e.g. Medplum bots), you can pre-compile template source files into a JSON map and then feed that map to an inline renderer.
+
+This package provides a CLI:
+
+```bash
+compile-react-email-templates [input-directory] [output-file]
+```
+
+Supported template extensions:
+
+- `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.cts`, `.mjs`, `.cjs`
+
+### Add to `package.json`
+
+```json
+{
+   "scripts": {
+      "compile-templates": "compile-react-email-templates ./notification-templates ./compiled-react-email-templates.json"
+   }
+}
+```
+
+### Run
+
+```bash
+npm run compile-templates
+```
+
+The output JSON uses template paths (relative to `input-directory`) as keys and raw template source as values.
 
 ## How it works
 
@@ -63,6 +97,27 @@ import { ReactEmailTemplateRendererFactory } from 'vintasend-react-email';
 const templateRenderer = new ReactEmailTemplateRendererFactory<MyConfig>().create();
 ```
 
+### 1.1) Create inline renderer instance (for pre-compiled templates)
+
+Use this when your runtime cannot read template files directly and you want to load templates from a JSON map.
+
+```ts
+import compiledTemplates from './compiled-react-email-templates.json';
+import { ReactEmailInlineTemplateRendererFactory } from 'vintasend-react-email';
+
+const inlineTemplateRenderer = new ReactEmailInlineTemplateRendererFactory<MyConfig>().create(
+   compiledTemplates,
+);
+```
+
+Expected map shape:
+
+```ts
+type CompiledTemplates = Record<string, string>;
+```
+
+Where keys match the values you pass in `notification.bodyTemplate` and `notification.subjectTemplate`.
+
 ### 2) Use with your adapter (example)
 
 ```ts
@@ -70,6 +125,12 @@ const templateRenderer = new ReactEmailTemplateRendererFactory<MyConfig>().creat
 const adapter = new SomeEmailAdapterFactory<MyConfig>().create(templateRenderer);
 ```
 
+Inline renderer with adapter:
+
+```ts
+const adapter = new SomeEmailAdapterFactory<MyConfig>().create(inlineTemplateRenderer);
+```
+
 ### 3) Template files
 
 `subject-template.ts`:

package/dist/index.d.ts

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

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -1 +1,2 @@
 export { ReactEmailTemplateRenderer, ReactEmailTemplateRendererFactory } from './react-email-template-renderer';
+export { ReactEmailInlineTemplateRenderer, ReactEmailInlineTemplateRendererFactory, } from './react-email-inline-template-renderer';

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

@@ -0,0 +1,24 @@
+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 ReactEmailInlineTemplateRenderer<Config extends BaseNotificationTypeConfig> implements BaseEmailTemplateRenderer<Config> {
+    private readonly templates;
+    private logger;
+    constructor(generatedTemplates: Record<string, string>);
+    injectLogger(logger: BaseLogger): void;
+    render(notification: DatabaseNotification<Config>, context: JsonObject): Promise<EmailTemplate>;
+    renderFromTemplateContent(notification: AnyNotification<Config>, templateContent: EmailTemplateContent, context: JsonObject): Promise<EmailTemplate>;
+    private compileSourceToCacheFile;
+    private loadTemplateFactoryFromContent;
+    private buildContentModuleSource;
+    private looksLikeTemplateModule;
+    private looksLikeFunctionBody;
+    private renderBodyOutput;
+    private renderSubjectOutput;
+}
+export declare class ReactEmailInlineTemplateRendererFactory<Config extends BaseNotificationTypeConfig> {
+    create(generatedTemplates: Record<string, string>): ReactEmailInlineTemplateRenderer<Config>;
+}
+//# sourceMappingURL=react-email-inline-template-renderer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"react-email-inline-template-renderer.d.ts","sourceRoot":"","sources":["../src/react-email-inline-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;AAWhG,qBAAa,gCAAgC,CAAC,MAAM,SAAS,0BAA0B,CACrF,YAAW,yBAAyB,CAAC,MAAM,CAAC;IAE5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,MAAM,CAA2B;gBAE7B,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAItD,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;IAsCnB,yBAAyB,CAC7B,YAAY,EAAE,eAAe,CAAC,MAAM,CAAC,EACrC,eAAe,EAAE,oBAAoB,EACrC,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,aAAa,CAAC;YAwBX,wBAAwB;YAwBxB,8BAA8B;IAiB5C,OAAO,CAAC,wBAAwB;IAmBhC,OAAO,CAAC,uBAAuB;IAI/B,OAAO,CAAC,qBAAqB;YAMf,gBAAgB;IAQ9B,OAAO,CAAC,mBAAmB;CAO5B;AAED,qBAAa,uCAAuC,CAAC,MAAM,SAAS,0BAA0B;IAC5F,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAGlD"}

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

@@ -0,0 +1,123 @@
+import { createHash } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, 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 COMPILED_TEMPLATE_CACHE_DIR = join(tmpdir(), 'vintasend-react-email-inline-templates');
+export class ReactEmailInlineTemplateRenderer {
+    constructor(generatedTemplates) {
+        this.logger = null;
+        this.templates = generatedTemplates;
+    }
+    injectLogger(logger) {
+        this.logger = logger;
+    }
+    async render(notification, context) {
+        this.logger?.info(`Rendering inline email template for notification ${notification.id}`);
+        const bodyTemplateKey = notification.bodyTemplate;
+        if (!bodyTemplateKey) {
+            throw new Error('Body template is required');
+        }
+        const bodyTemplateContent = this.templates[bodyTemplateKey];
+        if (bodyTemplateContent === undefined) {
+            throw new Error(`Body template "${bodyTemplateKey}" not found in templates`);
+        }
+        const subjectTemplateKey = notification.subjectTemplate;
+        if (!subjectTemplateKey) {
+            throw new Error('Subject template is required');
+        }
+        const subjectTemplateContent = this.templates[subjectTemplateKey];
+        if (subjectTemplateContent === undefined) {
+            throw new Error(`Subject template "${subjectTemplateKey}" not found in templates`);
+        }
+        const bodyTemplateFactory = await this.loadTemplateFactoryFromContent(bodyTemplateContent, 'body');
+        const subjectTemplateFactory = await this.loadTemplateFactoryFromContent(subjectTemplateContent, 'subject');
+        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 inline email template from content for notification ${notification.id}`);
+        if (!templateContent.subject) {
+            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 compileSourceToCacheFile(source, sourceIdentifier, loader) {
+        const sourceHash = createHash('sha1').update(`${sourceIdentifier}:${source}`).digest('hex');
+        const cacheFileName = `${sourceHash}-${loader}.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);
+    }
+    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 ReactEmailInlineTemplateRendererFactory {
+    create(generatedTemplates) {
+        return new ReactEmailInlineTemplateRenderer(generatedTemplates);
+    }
+}

package/dist/scripts/compile-react-email-templates.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Recursively finds all supported template files in a directory
+ */
+export declare function findTemplateFiles(dir: string, baseDir: string, files?: Map<string, string>): Map<string, string>;
+/**
+ * Main function to compile react email templates to JSON
+ */
+export declare function compileReactEmailTemplates(inputDir?: string, outputFile?: string): void;
+//# sourceMappingURL=compile-react-email-templates.d.ts.map

package/dist/scripts/compile-react-email-templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-react-email-templates.d.ts","sourceRoot":"","sources":["../../src/scripts/compile-react-email-templates.ts"],"names":[],"mappings":";AAoBA;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAa,GACrC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CA0BrB;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,GAAE,MAAsB,EAChC,UAAU,GAAE,MAA8C,GACzD,IAAI,CAyBN"}

package/dist/scripts/compile-react-email-templates.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+const SUPPORTED_TEMPLATE_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.mts',
+    '.cts',
+    '.mjs',
+    '.cjs',
+]);
+/**
+ * Recursively finds all supported template files in a directory
+ */
+export function findTemplateFiles(dir, baseDir, files = new Map()) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            findTemplateFiles(fullPath, baseDir, files);
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        const extension = path.extname(entry.name).toLowerCase();
+        if (!SUPPORTED_TEMPLATE_EXTENSIONS.has(extension)) {
+            continue;
+        }
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        const relativePath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
+        files.set(relativePath, content);
+    }
+    return files;
+}
+/**
+ * Main function to compile react email templates to JSON
+ */
+export function compileReactEmailTemplates(inputDir = './templates', outputFile = 'compiled-react-email-templates.json') {
+    if (!fs.existsSync(inputDir)) {
+        throw new Error(`Directory "${inputDir}" does not exist.`);
+    }
+    if (!fs.statSync(inputDir).isDirectory()) {
+        throw new Error(`"${inputDir}" is not a directory.`);
+    }
+    console.log(`Searching for template files in: ${inputDir}`);
+    const templateFiles = findTemplateFiles(inputDir, inputDir);
+    console.log(`Found ${templateFiles.size} template file(s)`);
+    const result = {};
+    for (const [filePath, content] of templateFiles.entries()) {
+        result[filePath] = content;
+        console.log(`  - ${filePath}`);
+    }
+    const outputContent = JSON.stringify(result, null, 2);
+    fs.writeFileSync(outputFile, outputContent, 'utf-8');
+    console.log(`\nSuccessfully compiled templates to: ${outputFile}`);
+}
+function runFromCli() {
+    const args = process.argv.slice(2);
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log('Usage: compile-react-email-templates [input-directory] [output-file]');
+        console.log('');
+        console.log('Arguments:');
+        console.log('  input-directory  Directory containing React Email templates (default: ./templates)');
+        console.log('  output-file      Output JSON file path (default: compiled-react-email-templates.json)');
+        console.log('');
+        console.log('Supported extensions: .ts, .tsx, .js, .jsx, .mts, .cts, .mjs, .cjs');
+        console.log('');
+        console.log('Examples:');
+        console.log('  compile-react-email-templates');
+        console.log('  compile-react-email-templates ./notification-templates');
+        console.log('  compile-react-email-templates ./notification-templates ./compiled-notification-templates.json');
+        process.exit(0);
+    }
+    const [inputDir, outputFile] = args;
+    try {
+        compileReactEmailTemplates(inputDir, outputFile);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Error: ${message}`);
+        process.exit(1);
+    }
+}
+const isCliEntryPoint = (() => {
+    const entry = process.argv[1];
+    if (!entry) {
+        return false;
+    }
+    try {
+        return pathToFileURL(entry).href === import.meta.url;
+    }
+    catch {
+        return false;
+    }
+})();
+if (isCliEntryPoint) {
+    runFromCli();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vintasend-react-email",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "VintaSend template renderer implementation for React Email",
   "main": "dist/index.js",
   "scripts": {
@@ -8,11 +8,16 @@
     "prepublishOnly": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "compile-templates": "compile-react-email-templates ./templates ./compiled-react-email-templates.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "src/scripts/compile-react-email-templates.ts"
   ],
+  "bin": {
+    "compile-react-email-templates": "dist/scripts/compile-react-email-templates.js"
+  },
   "author": "Hugo Bessa",
   "license": "MIT",
   "dependencies": {
@@ -20,9 +25,10 @@
     "esbuild": "^0.25.11",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
-    "vintasend": "^0.9.1"
+    "vintasend": "^0.10.0"
   },
   "devDependencies": {
+    "@types/node": "^25.3.3",
     "@vitest/coverage-v8": "4.0.18",
     "typescript": "^5.9.3",
     "vitest": "4.0.18"

package/src/scripts/compile-react-email-templates.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+interface ReactEmailTemplatesMap {
+  [key: string]: string;
+}
+
+const SUPPORTED_TEMPLATE_EXTENSIONS = new Set([
+  '.ts',
+  '.tsx',
+  '.js',
+  '.jsx',
+  '.mts',
+  '.cts',
+  '.mjs',
+  '.cjs',
+]);
+
+/**
+ * Recursively finds all supported template files in a directory
+ */
+export function findTemplateFiles(
+  dir: string,
+  baseDir: string,
+  files: Map<string, string> = new Map(),
+): Map<string, string> {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      findTemplateFiles(fullPath, baseDir, files);
+      continue;
+    }
+
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    const extension = path.extname(entry.name).toLowerCase();
+    if (!SUPPORTED_TEMPLATE_EXTENSIONS.has(extension)) {
+      continue;
+    }
+
+    const content = fs.readFileSync(fullPath, 'utf-8');
+    const relativePath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
+    files.set(relativePath, content);
+  }
+
+  return files;
+}
+
+/**
+ * Main function to compile react email templates to JSON
+ */
+export function compileReactEmailTemplates(
+  inputDir: string = './templates',
+  outputFile: string = 'compiled-react-email-templates.json',
+): void {
+  if (!fs.existsSync(inputDir)) {
+    throw new Error(`Directory "${inputDir}" does not exist.`);
+  }
+
+  if (!fs.statSync(inputDir).isDirectory()) {
+    throw new Error(`"${inputDir}" is not a directory.`);
+  }
+
+  console.log(`Searching for template files in: ${inputDir}`);
+
+  const templateFiles = findTemplateFiles(inputDir, inputDir);
+
+  console.log(`Found ${templateFiles.size} template file(s)`);
+
+  const result: ReactEmailTemplatesMap = {};
+  for (const [filePath, content] of templateFiles.entries()) {
+    result[filePath] = content;
+    console.log(`  - ${filePath}`);
+  }
+
+  const outputContent = JSON.stringify(result, null, 2);
+  fs.writeFileSync(outputFile, outputContent, 'utf-8');
+
+  console.log(`\nSuccessfully compiled templates to: ${outputFile}`);
+}
+
+function runFromCli(): void {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log('Usage: compile-react-email-templates [input-directory] [output-file]');
+    console.log('');
+    console.log('Arguments:');
+    console.log(
+      '  input-directory  Directory containing React Email templates (default: ./templates)',
+    );
+    console.log(
+      '  output-file      Output JSON file path (default: compiled-react-email-templates.json)',
+    );
+    console.log('');
+    console.log('Supported extensions: .ts, .tsx, .js, .jsx, .mts, .cts, .mjs, .cjs');
+    console.log('');
+    console.log('Examples:');
+    console.log('  compile-react-email-templates');
+    console.log('  compile-react-email-templates ./notification-templates');
+    console.log(
+      '  compile-react-email-templates ./notification-templates ./compiled-notification-templates.json',
+    );
+    process.exit(0);
+  }
+
+  const [inputDir, outputFile] = args;
+
+  try {
+    compileReactEmailTemplates(inputDir, outputFile);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Error: ${message}`);
+    process.exit(1);
+  }
+}
+
+const isCliEntryPoint = (() => {
+  const entry = process.argv[1];
+  if (!entry) {
+    return false;
+  }
+
+  try {
+    return pathToFileURL(entry).href === import.meta.url;
+  } catch {
+    return false;
+  }
+})();
+
+if (isCliEntryPoint) {
+  runFromCli();
+}