feat(react-email): add email config support

packages/react-email/package.json

@@ -49,7 +49,7 @@
     "debounce": "^2.0.0",
     "esbuild": "catalog:",
     "glob": "^13.0.6",
-    "jiti": "2.4.2",
+    "jiti": "catalog:",
     "log-symbols": "catalog:",
     "marked": "^15.0.12",
     "mime-types": "^3.0.0",

packages/react-email/src/cli/commands/build.ts

@@ -5,6 +5,7 @@ import { getPackages } from '@manypkg/get-packages';
 import logSymbols from 'log-symbols';
 import { installDependencies, type PackageManagerName, runScript } from 'nypm';
 import ora from 'ora';
+import { getEmailConfigPath } from '../../config/get-email-config-path.js';
 import {
   type EmailsDirectory,
   getEmailsDirectoryMetadata,
@@ -29,11 +30,13 @@ const setNextEnvironmentVariablesForBuild = async (
   if (isInReactEmailMonorepo) {
     rootDir = `'${await getPackages(usersProjectLocation).then((p) => p.rootDir.replaceAll('\\', '/'))}'`;
   }
+  const emailConfigPath = getEmailConfigPath(usersProjectLocation);
   const nextConfigContents = `
 import path from 'path';
 const emailsDirRelativePath = path.normalize('${emailsDirRelativePath}');
 const userProjectLocation = '${process.cwd().replaceAll('\\', '/')}';
 const previewServerLocation = '${builtPreviewAppPath.replaceAll('\\', '/')}';
+const emailConfigPath = ${emailConfigPath ? `'${emailConfigPath.replaceAll('\\', '/')}'` : 'undefined'};
 const rootDir = ${rootDir};
 /** @type {import('next').NextConfig} */
 const nextConfig = {
@@ -42,13 +45,14 @@ const nextConfig = {
     REACT_EMAIL_INTERNAL_EMAILS_DIR_RELATIVE_PATH: emailsDirRelativePath,
     REACT_EMAIL_INTERNAL_EMAILS_DIR_ABSOLUTE_PATH: path.resolve(userProjectLocation, emailsDirRelativePath),
     REACT_EMAIL_INTERNAL_PREVIEW_SERVER_LOCATION: previewServerLocation,
-    REACT_EMAIL_INTERNAL_USER_PROJECT_LOCATION: userProjectLocation
+    REACT_EMAIL_INTERNAL_USER_PROJECT_LOCATION: userProjectLocation,
+    REACT_EMAIL_INTERNAL_EMAIL_CONFIG_PATH: emailConfigPath
   },
   turbopack: {
     root: rootDir,
   },
   outputFileTracingRoot: rootDir,
-  serverExternalPackages: ['esbuild'],
+  serverExternalPackages: ['esbuild', 'jiti'],
   typescript: {
     ignoreBuildErrors: true
   },

packages/react-email/src/cli/commands/export.ts

@@ -9,6 +9,7 @@ import logSymbols from 'log-symbols';
 import normalize from 'normalize-path';
 import ora, { type Ora } from 'ora';
 import type React from 'react';
+import { getEmailConfig, getEmailConfigPath } from '../../config/index.js';
 import { renderingUtilitiesExporter } from '../utils/esbuild/renderring-utilities-exporter.js';
 import {
   type EmailsDirectory,
@@ -78,6 +79,10 @@ export const exportTemplates = async (
   const allTemplates = getEmailTemplatesFromDirectory(emailsDirectoryMetadata);
 
   try {
+    const emailConfigPath = getEmailConfigPath(process.cwd());
+    const emailConfig = await getEmailConfig(emailConfigPath);
+    const emailConfigPlugins = emailConfig.esbuild?.plugins ?? [];
+
     await build({
       bundle: true,
       entryPoints: allTemplates,
@@ -89,7 +94,10 @@ export const exportTemplates = async (
       outExtension: { '.js': '.cjs' },
       outdir: pathToWhereEmailMarkupShouldBeDumped,
       platform: 'node',
-      plugins: [renderingUtilitiesExporter(allTemplates)],
+      plugins: [
+        renderingUtilitiesExporter(allTemplates),
+        ...emailConfigPlugins,
+      ],
       write: true,
     });
   } catch (exception) {

packages/react-email/src/cli/commands/testing/export.spec.ts

@@ -1,7 +1,18 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
+import { build } from 'esbuild';
+import * as config from '../../../config/index.js';
 import { exportTemplates } from '../export.js';
 
+vi.mock('esbuild', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('esbuild')>();
+  return {
+    ...actual,
+    build: vi.fn(actual.build),
+  };
+});
+
 test('email export', { retry: 3 }, async () => {
   const pathToEmailsDirectory = path.resolve(__dirname, './emails');
   const pathToDumpMarkup = path.resolve(__dirname, './out');
@@ -212,3 +223,89 @@ test('email export', { retry: 3 }, async () => {
     "
   `);
 });
+
+test('email export uses email config plugins', async () => {
+  const temporaryProjectRoot = fs.mkdtempSync(
+    path.join(os.tmpdir(), 'react-email-export-config-'),
+  );
+  const previousWorkingDirectory = process.cwd();
+
+  try {
+    process.chdir(temporaryProjectRoot);
+
+    fs.mkdirSync(path.join(temporaryProjectRoot, 'emails'));
+    fs.writeFileSync(
+      path.join(temporaryProjectRoot, 'emails', 'test-email.js'),
+      `
+export default function Email() {
+  return null;
+}
+      `,
+      'utf8',
+    );
+    fs.writeFileSync(
+      path.join(temporaryProjectRoot, 'email.config.ts'),
+      'export default {};\n',
+      'utf8',
+    );
+
+    const mockedBuild = vi.mocked(build);
+    mockedBuild.mockClear();
+    mockedBuild.mockImplementation(async (options: any) => {
+      fs.mkdirSync(options.outdir, { recursive: true });
+      fs.writeFileSync(
+        path.join(options.outdir, 'test-email.cjs'),
+        `
+module.exports = {
+  default: function Email() {
+    return null;
+  },
+  render: async () => '<html><body>rendered</body></html>',
+  reactEmailCreateReactElement: (type, props) => ({ type, props }),
+};
+        `,
+        'utf8',
+      );
+
+      return { outputFiles: [] } as any;
+    });
+    const mockedGetEmailConfig = vi
+      .spyOn(config, 'getEmailConfig')
+      .mockResolvedValue({
+        esbuild: {
+          plugins: [{ name: 'email-config-plugin', setup: vi.fn() }],
+        },
+      });
+    const mockedGetEmailConfigPath = vi
+      .spyOn(config, 'getEmailConfigPath')
+      .mockReturnValue(path.join(temporaryProjectRoot, 'email.config.ts'));
+    mockedGetEmailConfig.mockClear();
+    mockedGetEmailConfigPath.mockClear();
+
+    const outDir = path.join(temporaryProjectRoot, 'out');
+    await exportTemplates(outDir, path.join(temporaryProjectRoot, 'emails'), {
+      silent: true,
+      pretty: true,
+    });
+
+    const calledConfigPath = mockedGetEmailConfig.mock.calls[0]?.[0];
+    expect(calledConfigPath).toContain('react-email-export-config-');
+    expect(path.basename(calledConfigPath ?? '')).toBe('email.config.ts');
+    const calledEmailConfigPathArg =
+      mockedGetEmailConfigPath.mock.calls[0]?.[0];
+    expect(calledEmailConfigPathArg).toContain('react-email-export-config-');
+    expect(path.basename(calledEmailConfigPathArg ?? '')).toBe(
+      path.basename(temporaryProjectRoot),
+    );
+    expect(mockedBuild).toHaveBeenCalledTimes(1);
+    expect(mockedBuild.mock.calls[0]?.[0].plugins).toEqual([
+      expect.objectContaining({ name: 'rendering-utilities-exporter' }),
+      expect.objectContaining({ name: 'email-config-plugin' }),
+    ]);
+    expect(fs.existsSync(path.join(outDir, 'test-email.html'))).toBe(true);
+  } finally {
+    process.chdir(previousWorkingDirectory);
+    fs.rmSync(temporaryProjectRoot, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  }
+});

packages/react-email/src/cli/utils/preview/get-env-variables-for-preview-app.spec.ts

@@ -0,0 +1,36 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { getEnvVariablesForPreviewApp } from './get-env-variables-for-preview-app';
+
+describe('getEnvVariablesForPreviewApp()', () => {
+  let temporaryDirectory = '';
+
+  beforeEach(() => {
+    temporaryDirectory = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'react-email-preview-env-'),
+    );
+  });
+
+  afterEach(() => {
+    fs.rmSync(temporaryDirectory, { recursive: true, force: true });
+  });
+
+  it('includes the discovered email config path', () => {
+    const emailConfigPath = path.join(temporaryDirectory, 'email.config.cts');
+    fs.writeFileSync(emailConfigPath, 'export default {};\n', 'utf8');
+
+    expect(
+      getEnvVariablesForPreviewApp('emails', '/preview', temporaryDirectory),
+    ).toMatchObject({
+      REACT_EMAIL_INTERNAL_EMAIL_CONFIG_PATH: emailConfigPath,
+      REACT_EMAIL_INTERNAL_EMAILS_DIR_RELATIVE_PATH: 'emails',
+      REACT_EMAIL_INTERNAL_EMAILS_DIR_ABSOLUTE_PATH: path.join(
+        temporaryDirectory,
+        'emails',
+      ),
+      REACT_EMAIL_INTERNAL_PREVIEW_SERVER_LOCATION: '/preview',
+      REACT_EMAIL_INTERNAL_USER_PROJECT_LOCATION: temporaryDirectory,
+    });
+  });
+});

packages/react-email/src/cli/utils/preview/get-env-variables-for-preview-app.ts

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { getEmailConfigPath } from '../../../config/get-email-config-path.js';
 
 export const getEnvVariablesForPreviewApp = (
   relativePathToEmailsDirectory: string,
@@ -15,6 +16,7 @@ export const getEnvVariablesForPreviewApp = (
     ),
     REACT_EMAIL_INTERNAL_PREVIEW_SERVER_LOCATION: previewServerLocation,
     REACT_EMAIL_INTERNAL_USER_PROJECT_LOCATION: cwd,
+    REACT_EMAIL_INTERNAL_EMAIL_CONFIG_PATH: getEmailConfigPath(cwd),
     REACT_EMAIL_INTERNAL_RESEND_API_KEY: resendApiKey,
   } as const;
 };

packages/react-email/src/cli/utils/tree.spec.ts

@@ -8,6 +8,7 @@ test('tree(__dirname, 2)', async () => {
     │   └── renderring-utilities-exporter.ts
     ├── preview
     │   ├── hot-reloading
+    │   ├── get-env-variables-for-preview-app.spec.ts
     │   ├── get-env-variables-for-preview-app.ts
     │   ├── index.ts
     │   ├── serve-static-file.ts

packages/react-email/src/config/get-email-config-path.spec.ts

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  getEmailConfigPath,
+  supportedEmailConfigFilenames,
+} from './get-email-config-path';
+
+describe('getEmailConfigPath()', () => {
+  let temporaryDirectory = '';
+
+  beforeEach(() => {
+    temporaryDirectory = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'react-email-config-path-'),
+    );
+  });
+
+  afterEach(() => {
+    fs.rmSync(temporaryDirectory, { recursive: true, force: true });
+  });
+
+  it('returns undefined when there is no config file', () => {
+    expect(getEmailConfigPath(temporaryDirectory)).toBeUndefined();
+  });
+
+  it.each(
+    supportedEmailConfigFilenames,
+  )('detects a %s config file', (filename) => {
+    const emailConfigPath = path.join(temporaryDirectory, filename);
+    fs.writeFileSync(emailConfigPath, 'export default {};\n', 'utf8');
+
+    expect(getEmailConfigPath(temporaryDirectory)).toBe(emailConfigPath);
+  });
+
+  it('prefers the first supported filename when multiple configs exist', () => {
+    for (const filename of supportedEmailConfigFilenames) {
+      fs.writeFileSync(
+        path.join(temporaryDirectory, filename),
+        'export default {};\n',
+        'utf8',
+      );
+    }
+
+    expect(getEmailConfigPath(temporaryDirectory)).toBe(
+      path.join(temporaryDirectory, supportedEmailConfigFilenames[0]!),
+    );
+  });
+});

packages/react-email/src/config/get-email-config-path.ts

@@ -0,0 +1,21 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const supportedEmailConfigFilenames = [
+  'email.config.ts',
+  'email.config.mts',
+  'email.config.cts',
+  'email.config.js',
+  'email.config.mjs',
+  'email.config.cjs',
+];
+
+export const getEmailConfigPath = (userProjectLocation: string) => {
+  for (const filename of supportedEmailConfigFilenames) {
+    const emailConfigPath = path.join(userProjectLocation, filename);
+
+    if (fs.existsSync(emailConfigPath)) {
+      return emailConfigPath;
+    }
+  }
+};

packages/react-email/src/config/get-email-config.spec.ts

@@ -0,0 +1,67 @@
+import { createJiti } from 'jiti';
+import { getEmailConfig } from './get-email-config';
+
+vi.mock('jiti', () => ({
+  createJiti: vi.fn(),
+}));
+
+describe('getEmailConfig()', () => {
+  const mockedCreateJiti = vi.mocked(createJiti);
+
+  beforeEach(() => {
+    mockedCreateJiti.mockReset();
+  });
+
+  it('returns an empty config when no path is provided', async () => {
+    await expect(getEmailConfig()).resolves.toEqual({});
+    expect(mockedCreateJiti).not.toHaveBeenCalled();
+  });
+
+  it('loads a config object from disk', async () => {
+    const importMock = vi.fn().mockResolvedValue({
+      esbuild: {
+        plugins: [{ name: 'test-plugin', setup: vi.fn() }],
+      },
+    });
+    mockedCreateJiti.mockReturnValue({
+      import: importMock,
+    } as unknown as ReturnType<typeof createJiti>);
+
+    const config = await getEmailConfig('/tmp/email.config.ts');
+
+    expect(config).toMatchObject({
+      esbuild: {
+        plugins: [{ name: 'test-plugin' }],
+      },
+    });
+
+    expect(mockedCreateJiti).toHaveBeenCalledWith('/tmp/email.config.ts');
+    expect(importMock).toHaveBeenCalledWith('/tmp/email.config.ts', {
+      default: true,
+    });
+  });
+
+  it('rejects configs that do not export an object', async () => {
+    mockedCreateJiti.mockReturnValue({
+      import: vi.fn().mockResolvedValue(null),
+    } as unknown as ReturnType<typeof createJiti>);
+
+    await expect(getEmailConfig('/tmp/email.config.ts')).rejects.toThrow(
+      'Expected React Email config at /tmp/email.config.ts to export an object.',
+    );
+  });
+
+  it('rejects configs with a non-array esbuild.plugins value', async () => {
+    mockedCreateJiti.mockReturnValue({
+      import: vi.fn().mockResolvedValue({
+        esbuild: {
+          plugins: {},
+        },
+      }),
+    } as unknown as ReturnType<typeof createJiti>);
+
+    await expect(getEmailConfig('/tmp/email.config.ts')).rejects.toThrow(
+      'Expected "esbuild.plugins" in React Email config at /tmp/email.config.ts to be an array.',
+    );
+  });
+});