react-email 6.10.0 → 6.11.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # react-email
 
+## 6.11.0
+
+### Minor Changes
+
+- 0432f96: Use custom esbuild plugins by passing the new `--esbuild-plugins` flag to `email dev`, `email build` and `email export`, so templates that need a custom compile-time transform can be previewed and exported.
+
 ## 6.10.0
 
 ### Minor Changes

package/dist/cli/index.mjs

@@ -6,7 +6,7 @@ import * as fs$1 from "node:fs";
 import fs, { existsSync, promises, statSync } from "node:fs";
 import * as path$2 from "node:path";
 import path from "node:path";
-import url, { fileURLToPath } from "node:url";
+import url, { fileURLToPath, pathToFileURL } from "node:url";
 import logSymbols from "log-symbols";
 import { addDevDependency, installDependencies, runScript } from "nypm";
 import * as fsp$1 from "node:fs/promises";
@@ -6533,7 +6533,7 @@ const getTracingRootDir = async (usersProjectLocation) => {
 //#region package.json
 var package_default = {
 	name: "react-email",
-	version: "6.10.0",
+	version: "6.11.0",
 	description: "A live preview of your emails right in your browser.",
 	bin: { "email": "./dist/cli/index.mjs" },
 	type: "module",
@@ -6739,8 +6739,9 @@ const stopSpinnerAndPersist = (spinner, display) => {
 //#endregion
 //#region src/cli/commands/build.ts
 const isInReactEmailMonorepo = !path.dirname(fileURLToPath(import.meta.url)).includes("node_modules");
-const setNextEnvironmentVariablesForBuild = async (emailsDirRelativePath, builtPreviewAppPath, usersProjectLocation) => {
+const setNextEnvironmentVariablesForBuild = async (emailsDirRelativePath, builtPreviewAppPath, usersProjectLocation, esbuildPluginsPath) => {
 	const rootDir = await getTracingRootDir(usersProjectLocation);
+	const esbuildPluginsAbsolutePath = esbuildPluginsPath ? path.resolve(usersProjectLocation, esbuildPluginsPath).replaceAll("\\", "/") : void 0;
 	const nextConfigContents = `
 import path from 'path';
 const emailsDirRelativePath = path.normalize('${emailsDirRelativePath}');
@@ -6754,13 +6755,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,
+    ${esbuildPluginsAbsolutePath ? `REACT_EMAIL_INTERNAL_ESBUILD_PLUGINS_PATH: '${esbuildPluginsAbsolutePath}',` : ""}
   },
   turbopack: {
     root: rootDir,
   },
   outputFileTracingRoot: rootDir,
-  serverExternalPackages: ['esbuild'],
+  serverExternalPackages: ['esbuild', 'jiti'],
   typescript: {
     ignoreBuildErrors: true
   },
@@ -6803,7 +6805,7 @@ const updatePackageJson = async (builtUiPath) => {
 	for (const [dependency, version] of Object.entries(packageJson.devDependencies)) packageJson.devDependencies[dependency] = version.replace("workspace:", "");
 	await fs.promises.writeFile(packageJsonPath, JSON.stringify(packageJson), "utf8");
 };
-const build$1 = async ({ dir: emailsDirRelativePath, packageManager }) => {
+const build$1 = async ({ dir: emailsDirRelativePath, packageManager, esbuildPlugins }) => {
 	if (packageManager) console.warn("The --packageManager option is deprecated and ignored. The build command now just uses npm.");
 	try {
 		const usersProjectLocation = process.cwd();
@@ -6837,7 +6839,7 @@ const build$1 = async ({ dir: emailsDirRelativePath, packageManager }) => {
 			await fs.promises.cp(staticPath, builtStaticDirectory, { recursive: true });
 		}
 		spinner.setText("Setting Next environment variables for preview app to work properly");
-		await setNextEnvironmentVariablesForBuild(emailsDirRelativePath, builtPreviewAppPath, usersProjectLocation);
+		await setNextEnvironmentVariablesForBuild(emailsDirRelativePath, builtPreviewAppPath, usersProjectLocation, esbuildPlugins);
 		spinner.setText("Setting server side generation for the email preview pages");
 		await forceSSGForEmailPreviews(emailsDirPath, builtPreviewAppPath);
 		spinner.setText("Updating package.json's build and start scripts");
@@ -7232,14 +7234,15 @@ const conf = new Conf({
 const styleText = nodeUtil.styleText ? nodeUtil.styleText : (_, text) => text;
 //#endregion
 //#region src/cli/utils/preview/get-env-variables-for-preview-app.ts
-const getEnvVariablesForPreviewApp = (relativePathToEmailsDirectory, previewServerLocation, cwd, resendApiKey, compatibilityClients) => {
+const getEnvVariablesForPreviewApp = (relativePathToEmailsDirectory, previewServerLocation, cwd, resendApiKey, compatibilityClients, esbuildPluginsPath) => {
 	return {
 		REACT_EMAIL_INTERNAL_EMAILS_DIR_RELATIVE_PATH: relativePathToEmailsDirectory,
 		REACT_EMAIL_INTERNAL_EMAILS_DIR_ABSOLUTE_PATH: path.resolve(cwd, relativePathToEmailsDirectory),
 		REACT_EMAIL_INTERNAL_PREVIEW_SERVER_LOCATION: previewServerLocation,
 		REACT_EMAIL_INTERNAL_USER_PROJECT_LOCATION: cwd,
 		REACT_EMAIL_INTERNAL_RESEND_API_KEY: resendApiKey,
-		...compatibilityClients !== void 0 && { COMPATIBILITY_EMAIL_CLIENTS: compatibilityClients }
+		...compatibilityClients !== void 0 && { COMPATIBILITY_EMAIL_CLIENTS: compatibilityClients },
+		...esbuildPluginsPath !== void 0 && { REACT_EMAIL_INTERNAL_ESBUILD_PLUGINS_PATH: path.resolve(cwd, esbuildPluginsPath) }
 	};
 };
 //#endregion
@@ -7294,7 +7297,7 @@ const safeAsyncServerListen = (server, port) => {
 		});
 	});
 };
-const startDevServer = async (emailsDirRelativePath, staticBaseDirRelativePath, port, compatibilityClients) => {
+const startDevServer = async (emailsDirRelativePath, staticBaseDirRelativePath, port, compatibilityClients, esbuildPluginsPath) => {
 	const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
 	if (major < 20 || major === 20 && minor < 19) {
 		console.error(` ${logSymbols.error}  Node ${process.versions.node} is not supported. Please upgrade to Node 20.19 or higher.`);
@@ -7328,7 +7331,7 @@ const startDevServer = async (emailsDirRelativePath, staticBaseDirRelativePath,
 	} else {
 		const nextPortToTry = port + 1;
 		console.warn(` ${logSymbols.warning} Port ${port} is already in use, trying ${nextPortToTry}`);
-		return startDevServer(emailsDirRelativePath, staticBaseDirRelativePath, nextPortToTry, compatibilityClients);
+		return startDevServer(emailsDirRelativePath, staticBaseDirRelativePath, nextPortToTry, compatibilityClients, esbuildPluginsPath);
 	}
 	devServer.on("close", async () => {
 		await app.close();
@@ -7350,7 +7353,7 @@ const startDevServer = async (emailsDirRelativePath, staticBaseDirRelativePath,
 	process.env = {
 		NODE_ENV: "development",
 		...process.env,
-		...getEnvVariablesForPreviewApp(path.normalize(emailsDirRelativePath), previewServerLocation, process.cwd(), conf.get("resendApiKey"), compatibilityClients)
+		...getEnvVariablesForPreviewApp(path.normalize(emailsDirRelativePath), previewServerLocation, process.cwd(), conf.get("resendApiKey"), compatibilityClients, esbuildPluginsPath)
 	};
 	if (!process.env.ESBUILD_BINARY_PATH) try {
 		const esbuild = createJiti(previewServer.esmResolve("esbuild"));
@@ -7449,13 +7452,13 @@ const tree = async (dirPath, depth) => {
 };
 //#endregion
 //#region src/cli/commands/dev.ts
-const dev = async ({ dir: emailsDirRelativePath, port, clients }) => {
+const dev = async ({ dir: emailsDirRelativePath, port, clients, esbuildPlugins }) => {
 	try {
 		if (!fs.existsSync(emailsDirRelativePath)) {
 			console.error(`Missing ${emailsDirRelativePath} folder`);
 			process.exit(1);
 		}
-		await setupHotreloading(await startDevServer(emailsDirRelativePath, emailsDirRelativePath, Number.parseInt(port, 10), clients), emailsDirRelativePath);
+		await setupHotreloading(await startDevServer(emailsDirRelativePath, emailsDirRelativePath, Number.parseInt(port, 10), clients, esbuildPlugins), emailsDirRelativePath);
 	} catch (error) {
 		console.log(error);
 		process.exit(1);
@@ -7489,12 +7492,26 @@ const inlineCssLoader = () => ({
 	}
 });
 //#endregion
+//#region src/cli/utils/esbuild/load-esbuild-plugins.ts
+/**
+* Loads the esbuild plugins a user wants applied when their templates are
+* bundled. The module's default export is either an array of plugins or a
+* function returning one, so plugins that need setup can do it lazily.
+*/
+const loadEsbuildPlugins = async (modulePath) => {
+	const exported = await createJiti(pathToFileURL(modulePath).href).import(modulePath, { default: true });
+	const plugins = typeof exported === "function" ? await exported() : exported;
+	if (!Array.isArray(plugins)) throw new Error(`Expected the default export of ${modulePath} to be an array of esbuild plugins or a function returning one`);
+	return plugins;
+};
+//#endregion
 //#region src/cli/utils/esbuild/escape-string-for-regex.ts
 function escapeStringForRegex(string) {
 	return string.replace(/[|\\{}()[\]^$+*?.]/g, "\\$&").replace(/-/g, "\\x2d");
 }
 //#endregion
 //#region src/cli/utils/esbuild/renderring-utilities-exporter.ts
+const ENTRY_SUFFIX = "?react-email-entry";
 /**
 * Made to export the `render` function out of the user's email template
 * so that issues like https://github.com/resend/react-email/issues/649 don't
@@ -7505,17 +7522,39 @@ function escapeStringForRegex(string) {
 *
 * This avoids multiple versions of React being involved, i.e., the version
 * in the CLI vs. the version the user has on their emails.
+*
+* Each template entry point is replaced by a wrapper module that re-exports
+* it along with the utilities, instead of loading the template's source here.
+* The template itself then goes through the regular load pipeline, so other
+* plugins (for example the user's `--esbuild-plugins`) can still transform it.
 */
 const renderingUtilitiesExporter = (emailTemplates) => ({
 	name: "rendering-utilities-exporter",
-	setup: (b) => {
-		b.onLoad({ filter: new RegExp(emailTemplates.map((emailPath) => escapeStringForRegex(emailPath)).join("|")) }, async ({ path: pathToFile }) => {
+	setup: async (b) => {
+		const templatePaths = await Promise.all(emailTemplates.map((emailPath) => promises.realpath(emailPath)));
+		const templateFilter = new RegExp(templatePaths.map((templatePath) => escapeStringForRegex(templatePath)).join("|"));
+		b.onResolve({ filter: /.*/ }, async (args) => {
+			if (args.kind !== "entry-point") return null;
+			const resolvedPath = path.isAbsolute(args.path) ? args.path : path.resolve(args.resolveDir, args.path);
+			const realPath = await promises.realpath(resolvedPath);
+			if (!templatePaths.includes(realPath)) return null;
 			return {
-				contents: `${await promises.readFile(pathToFile, "utf8")};
-          export { render } from 'react-email-module-that-will-export-render'
+				path: realPath,
+				suffix: ENTRY_SUFFIX
+			};
+		});
+		b.onLoad({ filter: templateFilter }, ({ path: pathToFile, suffix }) => {
+			if (suffix !== ENTRY_SUFFIX) return null;
+			const templateSpecifier = JSON.stringify(pathToFile);
+			return {
+				contents: `export * from ${templateSpecifier};
+          import * as emailModule from ${templateSpecifier};
+          export default emailModule.default;
+          export { render } from 'react-email-module-that-will-export-render';
           export { createElement as reactEmailCreateReactElement } from 'react';
         `,
-				loader: path.extname(pathToFile).slice(1)
+				loader: "js",
+				resolveDir: path.dirname(pathToFile)
 			};
 		});
 		b.onResolve({ filter: /^react-email-module-that-will-export-render$/ }, async (args) => {
@@ -7591,6 +7630,7 @@ const exportTemplates = async (pathToWhereEmailMarkupShouldBeDumped, emailsDirec
 	if (fs.existsSync(pathToWhereEmailMarkupShouldBeDumped)) fs.rmSync(pathToWhereEmailMarkupShouldBeDumped, { recursive: true });
 	const allTemplates = getEmailTemplatesFromDirectory(emailsDirectoryMetadata);
 	try {
+		const userPlugins = options.esbuildPlugins ? await loadEsbuildPlugins(path.resolve(process.cwd(), options.esbuildPlugins)) : [];
 		for (let i = 0; i < allTemplates.length; i += BUILD_BATCH_SIZE) {
 			const batch = allTemplates.slice(i, i + BUILD_BATCH_SIZE);
 			await build({
@@ -7604,7 +7644,11 @@ const exportTemplates = async (pathToWhereEmailMarkupShouldBeDumped, emailsDirec
 				outExtension: { ".js": ".cjs" },
 				outdir: pathToWhereEmailMarkupShouldBeDumped,
 				platform: "node",
-				plugins: [inlineCssLoader(), renderingUtilitiesExporter(batch)],
+				plugins: [
+					inlineCssLoader(),
+					renderingUtilitiesExporter(batch),
+					...userPlugins
+				],
 				write: true
 			});
 			await stop();
@@ -7788,14 +7832,15 @@ if (!requiredFlags.every((flag) => process.execArgv.includes(flag))) spawn(proce
 });
 else {
 	program.name("react-email").description("A live preview of your emails right in your browser").version(package_default.version);
-	program.command("dev").description("Starts the preview email development app").option("-d, --dir <path>", "Directory with your email templates", "./emails").option("-p --port <port>", "Port to run dev server on", "3000").option("-c, --clients <clients>", "Comma-separated list of email clients to show compatibility warnings for (overrides COMPATIBILITY_EMAIL_CLIENTS)", parseClientsOption).action(dev);
-	program.command("build").description("Copies the preview app for onto .react-email and builds it").option("-d, --dir <path>", "Directory with your email templates", "./emails").addOption(new Option("-p, --packageManager <name>").hideHelp()).action(build$1);
+	program.command("dev").description("Starts the preview email development app").option("-d, --dir <path>", "Directory with your email templates", "./emails").option("-p --port <port>", "Port to run dev server on", "3000").option("-c, --clients <clients>", "Comma-separated list of email clients to show compatibility warnings for (overrides COMPATIBILITY_EMAIL_CLIENTS)", parseClientsOption).option("--esbuild-plugins <path>", "Path to a module whose default export is an array of esbuild plugins (or a function returning one) applied when bundling email templates").action(dev);
+	program.command("build").description("Copies the preview app for onto .react-email and builds it").option("-d, --dir <path>", "Directory with your email templates", "./emails").addOption(new Option("-p, --packageManager <name>").hideHelp()).option("--esbuild-plugins <path>", "Path to a module whose default export is an array of esbuild plugins (or a function returning one) applied when bundling email templates").action(build$1);
 	program.command("start").description("Runs the built preview app that is inside of \".react-email\"").action(start);
-	program.command("export").description("Build the templates to the `out` directory").option("--outDir <path>", "Output directory", "out").option("-p, --pretty", "Pretty print the output", false).option("-t, --plainText", "Set output format as plain text", false).option("-d, --dir <path>", "Directory with your email templates", "./emails").option("-e, --extension <extension>", "Set a custom file extension for rendered emails (e.g. blade.php)").option("-s, --silent", "To, or not to show a spinner with process information", false).action(({ outDir, pretty, plainText, silent, dir: srcDir, extension }) => exportTemplates(outDir, srcDir, {
+	program.command("export").description("Build the templates to the `out` directory").option("--outDir <path>", "Output directory", "out").option("-p, --pretty", "Pretty print the output", false).option("-t, --plainText", "Set output format as plain text", false).option("-d, --dir <path>", "Directory with your email templates", "./emails").option("-e, --extension <extension>", "Set a custom file extension for rendered emails (e.g. blade.php)").option("-s, --silent", "To, or not to show a spinner with process information", false).option("--esbuild-plugins <path>", "Path to a module whose default export is an array of esbuild plugins (or a function returning one) applied when bundling email templates").action(({ outDir, pretty, plainText, silent, dir: srcDir, extension, esbuildPlugins }) => exportTemplates(outDir, srcDir, {
 		silent,
 		plainText,
 		pretty,
-		extension
+		extension,
+		esbuildPlugins
 	}));
 	const resend = program.command("resend");
 	resend.command("setup").description("Sets up the integration between the React Email CLI, and your Resend account through an API Key").action(resendSetup);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-email",
-  "version": "6.10.0",
+  "version": "6.11.0",
   "description": "A live preview of your emails right in your browser.",
   "bin": {
     "email": "./dist/cli/index.mjs"

package/readme.md

@@ -30,6 +30,14 @@ Starts a local development server that will watch your files and automatically r
 npx react-email dev
 ```
 
+Templates are bundled with [esbuild](https://esbuild.github.io/). To run additional esbuild plugins, for example a compile-time transform your templates depend on, pass `--esbuild-plugins` with the path to a module whose default export is an array of plugins (or a function returning one):
+
+```sh
+npx react-email dev --esbuild-plugins ./esbuild-plugins.mjs
+```
+
+The same option is accepted by `email build` and `email export`.
+
 ### `email export`
 
 Generates the plain HTML files of your emails into a `out` directory.