react-email 6.1.5 → 6.2.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # react-email
 
+## 6.2.0
+
+### Minor Changes
+
+- 192d82a: Add `theme` and `utility` props to `<Tailwind>` for Tailwind v4 CSS-first configuration. Both accept a CSS string and can be combined with the existing `config` prop.
+
+  ```tsx
+  import themeCss from "./theme.css?inline";
+
+  <Tailwind theme={themeCss}>
+    <div className="bg-brand font-display">Custom themed content</div>
+  </Tailwind>;
+  ```
+
+  Empty strings are no-ops. The base Tailwind theme and utilities are still loaded — `theme` and `utility` layer on top.
+
+  The preview server, `email export`, and the caniemail compatibility check all understand the Vite-style `?inline` and `?raw` suffixes on CSS imports, so the pattern above works the same in your project and inside the preview UI. The compatibility check also extracts the `theme` and `utility` props (in addition to `config`) when analyzing your template, so any caniemail incompatibilities in CSS produced by those props will surface as warnings.
+
+  Internal note: the exported `setupTailwind` helper now takes `{ config, cssConfigs }` instead of a positional `TailwindConfig`. Calling it with the old shape throws with a migration hint.
+
+### Patch Changes
+
+- 06f1d05: Watch directories targeted by dynamic `import()` template literals so changes to runtime-resolved files trigger preview reloads.
+
 ## 6.1.5
 
 ### Patch Changes

package/dist/cli/index.mjs

@@ -6523,7 +6523,7 @@ const getEmailsDirectoryMetadata = async (absolutePathToEmailsDirectory, keepFil
 //#region package.json
 var package_default = {
 	name: "react-email",
-	version: "6.1.5",
+	version: "6.2.0",
 	description: "A live preview of your emails right in your browser.",
 	bin: { "email": "./dist/cli/index.mjs" },
 	type: "module",
@@ -6864,7 +6864,8 @@ const build$1 = async ({ dir: emailsDirRelativePath, packageManager }) => {
 //#region src/cli/utils/preview/hot-reloading/get-imported-modules.ts
 const traverse = typeof traverseModule === "function" ? traverseModule : traverseModule.default;
 const getImportedModules = (contents) => {
-	const importedPaths = [];
+	const staticImports = [];
+	const dynamicImportPrefixes = [];
 	traverse(parse(contents, {
 		sourceType: "unambiguous",
 		strictMode: false,
@@ -6876,27 +6877,49 @@ const getImportedModules = (contents) => {
 		]
 	}), {
 		ImportDeclaration({ node }) {
-			importedPaths.push(node.source.value);
+			staticImports.push(node.source.value);
 		},
 		ExportAllDeclaration({ node }) {
-			importedPaths.push(node.source.value);
+			staticImports.push(node.source.value);
 		},
 		ExportNamedDeclaration({ node }) {
-			if (node.source) importedPaths.push(node.source.value);
+			if (node.source) staticImports.push(node.source.value);
 		},
 		TSExternalModuleReference({ node }) {
-			importedPaths.push(node.expression.value);
+			staticImports.push(node.expression.value);
 		},
 		CallExpression({ node }) {
 			if ("name" in node.callee && node.callee.name === "require") {
 				if (node.arguments.length === 1) {
 					const importPathNode = node.arguments[0];
-					if (importPathNode.type === "StringLiteral") importedPaths.push(importPathNode.value);
+					if (importPathNode.type === "StringLiteral") staticImports.push(importPathNode.value);
+				}
+				return;
+			}
+			if (node.callee.type === "Import" && node.arguments.length === 1) {
+				const argument = node.arguments[0];
+				if (argument.type === "StringLiteral") {
+					staticImports.push(argument.value);
+					return;
+				}
+				if (argument.type === "TemplateLiteral" && argument.quasis.length > 0) {
+					if (argument.expressions.length === 0) {
+						const onlyQuasi = argument.quasis[0];
+						const staticPath = onlyQuasi.value.cooked ?? onlyQuasi.value.raw;
+						if (staticPath.length > 0) staticImports.push(staticPath);
+						return;
+					}
+					const firstQuasi = argument.quasis[0];
+					const leadingStatic = firstQuasi.value.cooked ?? firstQuasi.value.raw;
+					if (leadingStatic.length > 0) dynamicImportPrefixes.push(leadingStatic);
 				}
 			}
 		}
 	});
-	return importedPaths;
+	return {
+		staticImports,
+		dynamicImportPrefixes
+	};
 };
 //#endregion
 //#region src/cli/utils/preview/hot-reloading/resolve-path-aliases.ts
@@ -6919,6 +6942,25 @@ const resolvePathAliases = (importPaths, projectPath) => {
 	}
 	return importPaths;
 };
+const isExistingDirectory = (candidate) => {
+	try {
+		return statSync(candidate).isDirectory();
+	} catch (_) {
+		return false;
+	}
+};
+const resolveAliasedDirectoryPrefix = (prefix, projectPath) => {
+	const configLoadResult = loadConfig(projectPath);
+	if (configLoadResult.resultType !== "success") return void 0;
+	return createMatchPath(configLoadResult.absoluteBaseUrl, configLoadResult.paths)(prefix, void 0, isExistingDirectory, [
+		".tsx",
+		".ts",
+		".js",
+		".jsx",
+		".cjs",
+		".mjs"
+	]) ?? void 0;
+};
 //#endregion
 //#region src/cli/utils/preview/hot-reloading/create-dependency-graph.ts
 const readAllFilesInsideDirectory = async (directory) => {
@@ -6951,6 +6993,34 @@ const checkFileExtensionsUntilItExists = (pathWithoutExtension) => {
 	if (existsSync(`${pathWithoutExtension}.mjs`)) return `${pathWithoutExtension}.mjs`;
 	if (existsSync(`${pathWithoutExtension}.cjs`)) return `${pathWithoutExtension}.cjs`;
 };
+const isUnderDirectory = (filePath, directoryPath) => {
+	if (filePath === directoryPath) return true;
+	const prefix = directoryPath.endsWith(path.sep) ? directoryPath : directoryPath + path.sep;
+	return filePath.startsWith(prefix);
+};
+const resolveDynamicImportDirectory = (prefix, filePath) => {
+	const moduleDirectory = path.dirname(filePath);
+	const normalizedPrefix = path.normalize(prefix);
+	const endsWithSeparator = normalizedPrefix.endsWith(path.sep);
+	const trimmed = endsWithSeparator ? normalizedPrefix.slice(0, -path.sep.length) : normalizedPrefix;
+	let resolvedPrefix;
+	if (prefix.startsWith(".") || path.isAbsolute(prefix)) resolvedPrefix = path.resolve(moduleDirectory, normalizedPrefix);
+	else {
+		if (trimmed.length === 0) return void 0;
+		const aliased = resolveAliasedDirectoryPrefix(trimmed, moduleDirectory);
+		if (aliased === void 0) return;
+		resolvedPrefix = aliased;
+	}
+	const directory = endsWithSeparator ? resolvedPrefix : path.dirname(resolvedPrefix);
+	if (isUnderDirectory(moduleDirectory, directory)) return void 0;
+	if (!existsSync(directory)) return void 0;
+	try {
+		if (!statSync(directory).isDirectory()) return void 0;
+	} catch (_) {
+		return;
+	}
+	return directory;
+};
 /**
 * Creates a stateful dependency graph that is structured in a way that you can get
 * the dependents of a module from its path.
@@ -6965,11 +7035,17 @@ const createDependencyGraph = async (directory) => {
 		path,
 		dependencyPaths: [],
 		dependentPaths: [],
+		dynamicDependencyDirectories: [],
 		moduleDependencies: []
 	}]));
 	const getDependencyPaths = async (filePath) => {
 		const contents = await promises.readFile(filePath, "utf8");
-		const importedPathsRelativeToDirectory = (isJavascriptModule(filePath) ? resolvePathAliases(getImportedModules(contents), path.dirname(filePath)) : []).map((dependencyPath) => {
+		const imports = isJavascriptModule(filePath) ? getImportedModules(contents) : {
+			staticImports: [],
+			dynamicImportPrefixes: []
+		};
+		const importedPathsRelativeToDirectory = (isJavascriptModule(filePath) ? resolvePathAliases(imports.staticImports, path.dirname(filePath)) : []).map((rawDependencyPath) => {
+			const dependencyPath = rawDependencyPath.split("?")[0];
 			if (!dependencyPath.startsWith(".") || path.isAbsolute(dependencyPath)) return dependencyPath;
 			let pathToDependencyFromDirectory = path.resolve(path.dirname(filePath), dependencyPath);
 			let isDirectory = false;
@@ -6994,7 +7070,8 @@ const createDependencyGraph = async (directory) => {
 		const moduleDependencies = importedPathsRelativeToDirectory.filter((dependencyPath) => !dependencyPath.startsWith(".") && !path.isAbsolute(dependencyPath));
 		return {
 			dependencyPaths: importedPathsRelativeToDirectory.filter((dependencyPath) => dependencyPath.startsWith(".") || path.isAbsolute(dependencyPath)),
-			moduleDependencies
+			moduleDependencies,
+			dynamicDependencyDirectories: Array.from(new Set(imports.dynamicImportPrefixes.map((prefix) => resolveDynamicImportDirectory(prefix, filePath)).filter((d) => typeof d === "string")))
 		};
 	};
 	const updateModuleDependenciesInGraph = async (moduleFilePath) => {
@@ -7002,10 +7079,12 @@ const createDependencyGraph = async (directory) => {
 			path: moduleFilePath,
 			dependencyPaths: [],
 			dependentPaths: [],
+			dynamicDependencyDirectories: [],
 			moduleDependencies: []
 		};
-		const { moduleDependencies, dependencyPaths: newDependencyPaths } = await getDependencyPaths(moduleFilePath);
+		const { moduleDependencies, dependencyPaths: newDependencyPaths, dynamicDependencyDirectories: newDynamicDependencyDirectories } = await getDependencyPaths(moduleFilePath);
 		graph[moduleFilePath].moduleDependencies = moduleDependencies;
+		graph[moduleFilePath].dynamicDependencyDirectories = newDynamicDependencyDirectories;
 		for (const dependencyPath of graph[moduleFilePath].dependencyPaths) {
 			if (newDependencyPaths.includes(dependencyPath)) continue;
 			const dependencyModule = graph[dependencyPath];
@@ -7055,6 +7134,10 @@ const createDependencyGraph = async (directory) => {
 		{ resolveDependentsOf: function resolveDependentsOf(pathToModule) {
 			const dependentPaths = /* @__PURE__ */ new Set();
 			const stack = [pathToModule];
+			for (const module of Object.values(graph)) for (const directory of module.dynamicDependencyDirectories) if (isUnderDirectory(pathToModule, directory) && module.path !== pathToModule && !dependentPaths.has(module.path)) {
+				dependentPaths.add(module.path);
+				stack.push(module.path);
+			}
 			while (stack.length > 0) {
 				const moduleEntry = graph[stack.pop()];
 				if (!moduleEntry) continue;
@@ -7094,6 +7177,13 @@ const setupHotreloading = async (devServer, emailDirRelativePath) => {
 	const getFilesOutsideEmailsDirectory = () => Object.keys(dependencyGraph).filter((p) => path.relative(absolutePathToEmailsDirectory, p).startsWith(".."));
 	let filesOutsideEmailsDirectory = getFilesOutsideEmailsDirectory();
 	for (const p of filesOutsideEmailsDirectory) watcher.add(p);
+	const getDynamicDependencyDirectories = () => {
+		const directories = /* @__PURE__ */ new Set();
+		for (const module of Object.values(dependencyGraph)) for (const directory of module.dynamicDependencyDirectories) directories.add(directory);
+		return [...directories];
+	};
+	let dynamicDependencyDirectories = getDynamicDependencyDirectories();
+	for (const directory of dynamicDependencyDirectories) watcher.add(directory);
 	const exit = async () => {
 		await watcher.close();
 	};
@@ -7107,6 +7197,10 @@ const setupHotreloading = async (devServer, emailDirRelativePath) => {
 		for (const p of filesOutsideEmailsDirectory) if (!newFilesOutsideEmailsDirectory.includes(p)) watcher.unwatch(p);
 		for (const p of newFilesOutsideEmailsDirectory) if (!filesOutsideEmailsDirectory.includes(p)) watcher.add(p);
 		filesOutsideEmailsDirectory = newFilesOutsideEmailsDirectory;
+		const newDynamicDependencyDirectories = getDynamicDependencyDirectories();
+		for (const directory of dynamicDependencyDirectories) if (!newDynamicDependencyDirectories.includes(directory)) watcher.unwatch(directory);
+		for (const directory of newDynamicDependencyDirectories) if (!dynamicDependencyDirectories.includes(directory)) watcher.add(directory);
+		dynamicDependencyDirectories = newDynamicDependencyDirectories;
 		changes.push({
 			event,
 			filename: relativePathToChangeTarget
@@ -7352,6 +7446,33 @@ const dev = async ({ dir: emailsDirRelativePath, port }) => {
 	}
 };
 //#endregion
+//#region src/cli/utils/esbuild/inline-css-loader.ts
+const inlineCssLoader = () => ({
+	name: "inline-css-loader",
+	setup(build) {
+		const namespace = "inline-css";
+		build.onResolve({ filter: /\?(inline|raw)(&|$)/ }, (args) => {
+			const [pathWithoutSuffix] = args.path.split("?");
+			if (!pathWithoutSuffix) return null;
+			return {
+				path: path.isAbsolute(pathWithoutSuffix) ? pathWithoutSuffix : path.resolve(args.resolveDir, pathWithoutSuffix),
+				namespace
+			};
+		});
+		build.onLoad({
+			filter: /.*/,
+			namespace
+		}, async (args) => {
+			const contents = await promises.readFile(args.path, "utf8");
+			return {
+				contents: `export default ${JSON.stringify(contents)};`,
+				loader: "js",
+				watchFiles: [args.path]
+			};
+		});
+	}
+});
+//#endregion
 //#region src/cli/utils/esbuild/escape-string-for-regex.ts
 function escapeStringForRegex(string) {
 	return string.replace(/[|\\{}()[\]^$+*?.]/g, "\\$&").replace(/-/g, "\\x2d");
@@ -7470,7 +7591,7 @@ const exportTemplates = async (pathToWhereEmailMarkupShouldBeDumped, emailsDirec
 				outExtension: { ".js": ".cjs" },
 				outdir: pathToWhereEmailMarkupShouldBeDumped,
 				platform: "node",
-				plugins: [renderingUtilitiesExporter(batch)],
+				plugins: [inlineCssLoader(), renderingUtilitiesExporter(batch)],
 				write: true
 			});
 			await stop();

package/dist/index.cjs

@@ -40434,11 +40434,17 @@ const css = `
 `;
 //#endregion
 //#region src/components/tailwind/utils/tailwindcss/setup-tailwind.ts
-async function setupTailwind(config) {
+const SETUP_TAILWIND_KEYS = new Set(["config", "cssConfigs"]);
+async function setupTailwind(props = {}) {
+	const stray = Object.keys(props).filter((k) => !SETUP_TAILWIND_KEYS.has(k));
+	if (stray.length > 0) throw new Error(`setupTailwind now takes { config, cssConfigs } — received unexpected keys: ${stray.join(", ")}. If you used to call setupTailwind(config), wrap it: setupTailwind({ config }).`);
+	const { config, cssConfigs } = props;
 	const baseCss = `
 @layer theme, base, components, utilities;
 @import "tailwindcss/theme.css" layer(theme);
 @import "tailwindcss/utilities.css" layer(utilities);
+${cssConfigs?.theme ? "@import \"custom-theme.css\" layer(theme);" : ""}
+${cssConfigs?.utility ? "@import \"custom-utilities.css\" layer(utilities);" : ""}
 @config;
 `;
 	const compiler = await (0, tailwindcss.compile)(baseCss, {
@@ -40446,7 +40452,7 @@ async function setupTailwind(config) {
 			if (resourceHint === "config") return {
 				path: id,
 				base,
-				module: config
+				module: config ?? {}
 			};
 			throw new Error(`NO-OP: should we implement support for ${resourceHint}?`);
 		},
@@ -40472,6 +40478,16 @@ async function setupTailwind(config) {
 				path: id,
 				content: css
 			};
+			if (id === "custom-theme.css") return {
+				base,
+				path: id,
+				content: cssConfigs?.theme ?? ""
+			};
+			if (id === "custom-utilities.css") return {
+				base,
+				path: id,
+				content: cssConfigs?.utility ?? ""
+			};
 			throw new Error("stylesheet not supported, you can only import the ones from tailwindcss");
 		}
 	});
@@ -40541,8 +40557,15 @@ const pixelBasedPreset = { theme: { extend: {
 		96: "384px"
 	}
 } } };
-function Tailwind({ children, config }) {
-	const tailwindSetup = useSuspensedPromise(() => setupTailwind(config ?? {}), JSON.stringify(config, (_key, value) => typeof value === "function" ? value.toString() : value));
+function Tailwind({ children, config, theme, utility }) {
+	const twConfigData = {
+		config,
+		cssConfigs: {
+			theme,
+			utility
+		}
+	};
+	const tailwindSetup = useSuspensedPromise(() => setupTailwind(twConfigData), JSON.stringify(twConfigData, (_key, value) => typeof value === "function" ? value.toString() : value));
 	let classesUsed = [];
 	let mappedChildren = mapReactTree(children, (node) => {
 		if (react.isValidElement(node)) {

package/dist/index.d.cts

@@ -5085,24 +5085,36 @@ declare function sanitizeStyleSheet(styleSheet: StyleSheet): void;
 //#endregion
 //#region src/components/tailwind/tailwind.d.ts
 type TailwindConfig = Omit<Config, 'content'>;
-interface TailwindProps {
-  children: React$2.ReactNode;
-  config?: TailwindConfig;
-}
 interface EmailElementProps {
   children?: React$2.ReactNode;
   className?: string;
   style?: React$2.CSSProperties;
 }
 declare const pixelBasedPreset: TailwindConfig;
+interface TailwindProps {
+  children: React$2.ReactNode;
+  config?: TailwindConfig;
+  theme?: string;
+  utility?: string;
+}
 declare function Tailwind({
   children,
-  config
+  config,
+  theme,
+  utility
 }: TailwindProps): React$2.ReactNode;
 //#endregion
 //#region src/components/tailwind/utils/tailwindcss/setup-tailwind.d.ts
 type TailwindSetup = Awaited<ReturnType<typeof setupTailwind>>;
-declare function setupTailwind(config: TailwindConfig): Promise<{
+interface CSSConfigs {
+  theme?: string;
+  utility?: string;
+}
+interface SetupTailwindProps {
+  config?: TailwindConfig;
+  cssConfigs?: CSSConfigs;
+}
+declare function setupTailwind(props?: SetupTailwindProps): Promise<{
   addUtilities: (candidates: string[]) => void;
   getStyleSheet: () => StyleSheet;
 }>;

package/dist/index.d.mts

@@ -5085,24 +5085,36 @@ declare function sanitizeStyleSheet(styleSheet: StyleSheet): void;
 //#endregion
 //#region src/components/tailwind/tailwind.d.ts
 type TailwindConfig = Omit<Config, 'content'>;
-interface TailwindProps {
-  children: React$2.ReactNode;
-  config?: TailwindConfig;
-}
 interface EmailElementProps {
   children?: React$2.ReactNode;
   className?: string;
   style?: React$2.CSSProperties;
 }
 declare const pixelBasedPreset: TailwindConfig;
+interface TailwindProps {
+  children: React$2.ReactNode;
+  config?: TailwindConfig;
+  theme?: string;
+  utility?: string;
+}
 declare function Tailwind({
   children,
-  config
+  config,
+  theme,
+  utility
 }: TailwindProps): React$2.ReactNode;
 //#endregion
 //#region src/components/tailwind/utils/tailwindcss/setup-tailwind.d.ts
 type TailwindSetup = Awaited<ReturnType<typeof setupTailwind>>;
-declare function setupTailwind(config: TailwindConfig): Promise<{
+interface CSSConfigs {
+  theme?: string;
+  utility?: string;
+}
+interface SetupTailwindProps {
+  config?: TailwindConfig;
+  cssConfigs?: CSSConfigs;
+}
+declare function setupTailwind(props?: SetupTailwindProps): Promise<{
   addUtilities: (candidates: string[]) => void;
   getStyleSheet: () => StyleSheet;
 }>;

package/dist/index.mjs

@@ -40413,11 +40413,17 @@ const css = `
 `;
 //#endregion
 //#region src/components/tailwind/utils/tailwindcss/setup-tailwind.ts
-async function setupTailwind(config) {
+const SETUP_TAILWIND_KEYS = new Set(["config", "cssConfigs"]);
+async function setupTailwind(props = {}) {
+	const stray = Object.keys(props).filter((k) => !SETUP_TAILWIND_KEYS.has(k));
+	if (stray.length > 0) throw new Error(`setupTailwind now takes { config, cssConfigs } — received unexpected keys: ${stray.join(", ")}. If you used to call setupTailwind(config), wrap it: setupTailwind({ config }).`);
+	const { config, cssConfigs } = props;
 	const baseCss = `
 @layer theme, base, components, utilities;
 @import "tailwindcss/theme.css" layer(theme);
 @import "tailwindcss/utilities.css" layer(utilities);
+${cssConfigs?.theme ? "@import \"custom-theme.css\" layer(theme);" : ""}
+${cssConfigs?.utility ? "@import \"custom-utilities.css\" layer(utilities);" : ""}
 @config;
 `;
 	const compiler = await compile(baseCss, {
@@ -40425,7 +40431,7 @@ async function setupTailwind(config) {
 			if (resourceHint === "config") return {
 				path: id,
 				base,
-				module: config
+				module: config ?? {}
 			};
 			throw new Error(`NO-OP: should we implement support for ${resourceHint}?`);
 		},
@@ -40451,6 +40457,16 @@ async function setupTailwind(config) {
 				path: id,
 				content: css
 			};
+			if (id === "custom-theme.css") return {
+				base,
+				path: id,
+				content: cssConfigs?.theme ?? ""
+			};
+			if (id === "custom-utilities.css") return {
+				base,
+				path: id,
+				content: cssConfigs?.utility ?? ""
+			};
 			throw new Error("stylesheet not supported, you can only import the ones from tailwindcss");
 		}
 	});
@@ -40520,8 +40536,15 @@ const pixelBasedPreset = { theme: { extend: {
 		96: "384px"
 	}
 } } };
-function Tailwind({ children, config }) {
-	const tailwindSetup = useSuspensedPromise(() => setupTailwind(config ?? {}), JSON.stringify(config, (_key, value) => typeof value === "function" ? value.toString() : value));
+function Tailwind({ children, config, theme, utility }) {
+	const twConfigData = {
+		config,
+		cssConfigs: {
+			theme,
+			utility
+		}
+	};
+	const tailwindSetup = useSuspensedPromise(() => setupTailwind(twConfigData), JSON.stringify(twConfigData, (_key, value) => typeof value === "function" ? value.toString() : value));
 	let classesUsed = [];
 	let mappedChildren = mapReactTree(children, (node) => {
 		if (React$1.isValidElement(node)) {

package/package.json

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

package/src/components/tailwind/tailwind.spec.tsx

@@ -899,6 +899,321 @@ describe('Tailwind component', () => {
     });
   });
 
+  describe('with css configuration', () => {
+    it('handles empty theme string', async () => {
+      const actualOutput = await render(
+        <Tailwind theme="">
+          <div className="bg-red-500 text-white">Default utilities</div>
+        </Tailwind>,
+      ).then(pretty);
+
+      expect(actualOutput).toMatchInlineSnapshot(`
+        "<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+        <!--$-->
+        <div style="background-color:rgb(251,44,54);color:rgb(255,255,255)">
+          Default utilities
+        </div>
+        <!--/$-->
+        "
+      `);
+    });
+
+    it('supports custom colors', async () => {
+      const theme = `
+      @theme {
+        --color-custom: #1fb6ff;
+      }
+      `;
+
+      const actualOutput = await render(
+        <Tailwind theme={theme}>
+          <div className="bg-custom text-custom" />
+        </Tailwind>,
+      ).then(pretty);
+
+      expect(actualOutput).toMatchInlineSnapshot(`
+        "<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+        <!--$-->
+        <div style="background-color:rgb(31,182,255);color:rgb(31,182,255)"></div>
+        <!--/$-->
+        "
+      `);
+    });
+
+    it('supports custom fonts', async () => {
+      const theme = `
+      @theme {
+        --font-sans: "Graphik", sans-serif;
+        --font-serif: "Merriweather", serif;
+      }
+      `;
+
+      const actualOutput = await render(
+        <Tailwind theme={theme}>
+          <div className="font-sans" />
+          <div className="font-serif" />
+        </Tailwind>,
+      ).then(pretty);
+
+      expect(actualOutput).toMatchInlineSnapshot(`
+        "<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+        <!--$-->
+        <div style='font-family:"Graphik",sans-serif'></div>
+        <div style='font-family:"Merriweather",serif'></div>
+        <!--/$-->
+        "
+      `);
+    });
+
+    it('supports custom spacing', async () => {
+      const theme = `
+        @theme {
+          --spacing-8xl: 96rem;
+        }
+      `;
+
+      const actualOutput = await render(
+        <Tailwind theme={theme}>
+          <div className="m-8xl" />
+        </Tailwind>,
+      ).then(pretty);
+      expect(actualOutput).toMatchInlineSnapshot(`
+        "<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+        <!--$-->
+        <div style="margin:96rem"></div>
+        <!--/$-->
+        "
+      `);
+    });
+
+    it('supports custom border radius', async () => {
+      const theme = `
+        @theme {
+          --border-radius-4xl: 2rem;
+        }
+      `;
+
+      const actualOutput = await render(
+        <Tailwind theme={theme}>
+          <div className="rounded-4xl" />
+        </Tailwind>,
+      ).then(pretty);
+      expect(actualOutput).toMatchInlineSnapshot(`
+        "<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+        <!--$-->
+        <div style="border-radius:2rem"></div>
+        <!--/$-->
+        "
+      `);
+    });
+
+    it('supports custom text alignment', async () => {
+      const theme = `
+        @theme {
+          --text-align-justify: justify;
+        }
+      `;
+
+      const actualOutput = await render(
+        <Tailwind theme={theme}>
+          <div className="text-justify" />
+        </Tailwind>,
+      ).then(pretty);
+
+      expect(actualOutput).toMatchInlineSnapshot(`
+        "<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+        <!--$-->
+        <div style="text-align:justify"></div>
+        <!--/$-->
+        "
+      `);
+    });
+
+    it('supports both config and theme props together', async () => {
+      const customConfig = {
+        theme: {
+          extend: {
+            colors: {
+              primary: '#ff0000',
+            },
+          },
+        },
+      } satisfies TailwindConfig;
+
+      const customTheme = `
+        @theme {
+          --color-secondary: #00ff00;
+        }
+      `;
+
+      const actualOutput = await render(
+        <Tailwind config={customConfig} theme={customTheme}>
+          <div className="bg-primary text-secondary">Both config and theme</div>
+        </Tailwind>,
+      ).then(pretty);
+
+      expect(actualOutput).toMatchInlineSnapshot(`
+        "<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+        <!--$-->
+        <div style="background-color:rgb(255,0,0);color:rgb(0,255,0)">
+          Both config and theme
+        </div>
+        <!--/$-->
+        "
+      `);
+    });
+  });
+
+  describe('with utilities', () => {
+    it('handles empty utilities string', async () => {
+      const actualOutput = await render(
+        <Tailwind utility="">
+          <div className="bg-red-500 text-white">Default utilities</div>
+        </Tailwind>,
+      ).then(pretty);
+
+      expect(actualOutput).toMatchInlineSnapshot(`
+        "<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+        <!--$-->
+        <div style="background-color:rgb(251,44,54);color:rgb(255,255,255)">
+          Default utilities
+        </div>
+        <!--/$-->
+        "
+      `);
+    });
+
+    it('supports custom utilities', async () => {
+      const utilities = `
+      .custom-shadow {
+        box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+        border-radius: 8px;
+        padding: 16px;
+      }
+      `;
+
+      const actualOutput = await render(
+        <Tailwind utility={utilities}>
+          <div className="custom-shadow" />
+        </Tailwind>,
+      ).then(pretty);
+
+      expect(actualOutput).toMatchInlineSnapshot(`
+        "<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+        <!--$-->
+        <div
+          style="box-shadow:0 4px 6px rgba(0,0,0,0.1);border-radius:8px;padding:16px"></div>
+        <!--/$-->
+        "
+      `);
+    });
+
+    it('supports animations', async () => {
+      const utilities = `
+        .pulse-animation {
+          animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+        }
+      `;
+
+      const actualOutput = await render(
+        <Tailwind utility={utilities}>
+          <div className="pulse-animation" />
+        </Tailwind>,
+      ).then(pretty);
+
+      expect(actualOutput).toMatchInlineSnapshot(`
+        "<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+        <!--$-->
+        <div style="animation:pulse 2s cubic-bezier(0.4,0,0.6,1) infinite"></div>
+        <!--/$-->
+        "
+      `);
+    });
+
+    it('supports both config and utilities props together', async () => {
+      const customConfig = {
+        theme: {
+          extend: {
+            colors: {
+              primary: '#ff0000',
+            },
+          },
+        },
+      } satisfies TailwindConfig;
+
+      const customUtilities = `
+        .card-base {
+          border: 1px solid #e5e7eb;
+          padding: 20px;
+        }
+      `;
+
+      const actualOutput = await render(
+        <Tailwind config={customConfig} utility={customUtilities}>
+          <div className="bg-primary card-base">Config and utilities</div>
+        </Tailwind>,
+      ).then(pretty);
+
+      expect(actualOutput).toMatchInlineSnapshot(`
+        "<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+        <!--$-->
+        <div
+          style="background-color:rgb(255,0,0);border:1px solid rgb(229,231,235);padding:20px">
+          Config and utilities
+        </div>
+        <!--/$-->
+        "
+      `);
+    });
+
+    it('supports config, theme, and utilities together', async () => {
+      const customConfig = {
+        theme: {
+          extend: {
+            colors: {
+              primary: '#ff0000',
+            },
+          },
+        },
+      } satisfies TailwindConfig;
+
+      const customTheme = `
+        @theme {
+          --color-secondary: #00ff00;
+        }
+      `;
+
+      const customUtilities = `
+        .special-border {
+          border: 2px dashed #0000ff;
+        }
+      `;
+
+      const actualOutput = await render(
+        <Tailwind
+          config={customConfig}
+          theme={customTheme}
+          utility={customUtilities}
+        >
+          <div className="bg-primary text-secondary special-border">
+            All three props
+          </div>
+        </Tailwind>,
+      ).then(pretty);
+
+      expect(actualOutput).toMatchInlineSnapshot(`
+        "<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+        <!--$-->
+        <div
+          style="background-color:rgb(255,0,0);color:rgb(0,255,0);border:2px dashed rgb(0,0,255)">
+          All three props
+        </div>
+        <!--/$-->
+        "
+      `);
+    });
+  });
+
   describe('with custom plugins config', () => {
     const config = {
       plugins: [

package/src/components/tailwind/tailwind.tsx

@@ -13,11 +13,6 @@ import { setupTailwind } from './utils/tailwindcss/setup-tailwind.js';
 
 export type TailwindConfig = Omit<Config, 'content'>;
 
-export interface TailwindProps {
-  children: React.ReactNode;
-  config?: TailwindConfig;
-}
-
 export interface EmailElementProps {
   children?: React.ReactNode;
   className?: string;
@@ -83,15 +78,29 @@ export const pixelBasedPreset: TailwindConfig = {
   },
 };
 
-export function Tailwind({ children, config }: TailwindProps) {
+export interface TailwindProps {
+  children: React.ReactNode;
+  config?: TailwindConfig;
+  theme?: string;
+  utility?: string;
+}
+
+export function Tailwind({ children, config, theme, utility }: TailwindProps) {
+  const twConfigData = {
+    config,
+    cssConfigs: {
+      theme,
+      utility,
+    },
+  };
   const tailwindSetup = useSuspensedPromise(
-    () => setupTailwind(config ?? {}),
-    JSON.stringify(config, (_key, value) =>
+    () => setupTailwind(twConfigData),
+    JSON.stringify(twConfigData, (_key, value) =>
       typeof value === 'function' ? value.toString() : value,
     ),
   );
-  let classesUsed: string[] = [];
 
+  let classesUsed: string[] = [];
   let mappedChildren: React.ReactNode = mapReactTree(children, (node) => {
     if (React.isValidElement<EmailElementProps>(node)) {
       if (node.props.className) {

package/src/components/tailwind/utils/css/extract-rules-per-class.spec.ts

@@ -80,17 +80,19 @@ describe('extractRulesPerClass()', async () => {
 
   it('splits mixed rules (base + media) into inlinable base and non-inlinable media', async () => {
     const tailwind = await setupTailwind({
-      plugins: [
-        {
-          handler: (api) => {
-            api.addUtilities({
-              '.text-body': {
-                '@apply text-[green] sm:text-[darkgreen]': {},
-              },
-            });
+      config: {
+        plugins: [
+          {
+            handler: (api) => {
+              api.addUtilities({
+                '.text-body': {
+                  '@apply text-[green] sm:text-[darkgreen]': {},
+                },
+              });
+            },
           },
-        },
-      ],
+        ],
+      },
     });
     const classes = ['text-body'];
     tailwind.addUtilities(classes);
@@ -115,17 +117,19 @@ describe('extractRulesPerClass()', async () => {
 
   it('treats rules with pseudo-selectors as fully non-inlinable', async () => {
     const tailwind = await setupTailwind({
-      plugins: [
-        {
-          handler: (api) => {
-            api.addUtilities({
-              '.btn:hover': {
-                color: 'red',
-              },
-            });
+      config: {
+        plugins: [
+          {
+            handler: (api) => {
+              api.addUtilities({
+                '.btn:hover': {
+                  color: 'red',
+                },
+              });
+            },
           },
-        },
-      ],
+        ],
+      },
     });
     const classes = ['btn'];
     tailwind.addUtilities(classes);

package/src/components/tailwind/utils/tailwindcss/setup-tailwind.spec.ts

@@ -16,3 +16,10 @@ test('setupTailwind() and addUtilities()', async () => {
     `"/*! tailwindcss v4.1.18 | MIT License | https://tailwindcss.com */@layer theme,base,components,utilities;@layer theme{:root,:host{--color-red-100: oklch(93.6% 0.032 17.717);--color-red-500: oklch(63.7% 0.237 25.331);--color-blue-300: oklch(80.9% 0.105 251.813);--color-slate-900: oklch(20.8% 0.042 265.755)}}@layer utilities{.bg-red-100{background-color:var(--color-red-100)}.bg-slate-900{background-color:var(--color-slate-900)}.text-red-500{color:var(--color-red-500)}.sm\\:bg-blue-300{@media (width>=40rem){background-color:var(--color-blue-300)}}}"`,
   );
 });
+
+test('setupTailwind() throws on legacy positional config shape', async () => {
+  await expect(
+    // @ts-expect-error — intentionally calling with the old shape to verify the guard
+    setupTailwind({ plugins: [], theme: { extend: {} } }),
+  ).rejects.toThrowError(/setupTailwind now takes \{ config, cssConfigs \}/);
+});

package/src/components/tailwind/utils/tailwindcss/setup-tailwind.ts

@@ -8,20 +8,43 @@ import utilitiesCss from './tailwind-stylesheets/utilities.js';
 
 export type TailwindSetup = Awaited<ReturnType<typeof setupTailwind>>;
 
-export async function setupTailwind(config: TailwindConfig) {
+interface CSSConfigs {
+  theme?: string;
+  utility?: string;
+}
+
+interface SetupTailwindProps {
+  config?: TailwindConfig;
+  cssConfigs?: CSSConfigs;
+}
+
+const SETUP_TAILWIND_KEYS = new Set(['config', 'cssConfigs']);
+
+export async function setupTailwind(props: SetupTailwindProps = {}) {
+  const stray = Object.keys(props).filter((k) => !SETUP_TAILWIND_KEYS.has(k));
+  if (stray.length > 0) {
+    throw new Error(
+      `setupTailwind now takes { config, cssConfigs } — received unexpected keys: ${stray.join(', ')}. ` +
+        'If you used to call setupTailwind(config), wrap it: setupTailwind({ config }).',
+    );
+  }
+  const { config, cssConfigs } = props;
   const baseCss = `
 @layer theme, base, components, utilities;
 @import "tailwindcss/theme.css" layer(theme);
 @import "tailwindcss/utilities.css" layer(utilities);
+${cssConfigs?.theme ? '@import "custom-theme.css" layer(theme);' : ''}
+${cssConfigs?.utility ? '@import "custom-utilities.css" layer(utilities);' : ''}
 @config;
 `;
+
   const compiler = await compile(baseCss, {
     async loadModule(id, base, resourceHint) {
       if (resourceHint === 'config') {
         return {
           path: id,
           base: base,
-          module: config,
+          module: config ?? {},
         };
       }
 
@@ -63,6 +86,22 @@ export async function setupTailwind(config: TailwindConfig) {
         };
       }
 
+      if (id === 'custom-theme.css') {
+        return {
+          base,
+          path: id,
+          content: cssConfigs?.theme ?? '',
+        };
+      }
+
+      if (id === 'custom-utilities.css') {
+        return {
+          base,
+          path: id,
+          content: cssConfigs?.utility ?? '',
+        };
+      }
+
       throw new Error(
         'stylesheet not supported, you can only import the ones from tailwindcss',
       );