feat(render): add withRenderOptions higher-order function

emiliosheinz · emiliosheinz · commit 7e6ef4b0192c · 2025-08-14T21:11:26.000-03:00
This commit introduces `withRenderOptions`, a higher-order function that enables email templates to access render options (like plainText mode) directly as props. This allows templates to conditionally render different content based on the rendering context.

Key changes:

- Added `withRenderOptions` higher-order function that marks components to receive render options
- Implemented `injectRenderOptions` to automatically pass options to wrapped components during rendering
- Updated both browser and node render functions to inject options before rendering
- Added comprehensive tests for both wrapped and unwrapped components
- Exported new types and utilities from package entry points
diff --git a/packages/render/src/browser/index.ts b/packages/render/src/browser/index.ts
@@ -11,4 +11,5 @@ export const renderAsync = (element: React.ReactElement, options?: Options) => {
 export * from '../shared/options';
 export * from '../shared/plain-text-selectors';
 export * from '../shared/utils/pretty';
+export { type PropsWithRenderOptions, withRenderOptions } from '../shared/with-render-options';
 export * from './render';
diff --git a/packages/render/src/browser/render-web.spec.tsx b/packages/render/src/browser/render-web.spec.tsx
@@ -4,9 +4,11 @@
 
 import { createElement } from 'react';
 import usePromise from 'react-promise-suspense';
+import type { Options } from '../shared/options';
 import { Preview } from '../shared/utils/preview';
 import { Template } from '../shared/utils/template';
 import { render } from './render';
+import { withRenderOptions } from '../shared/with-render-options';
 
 type Import = typeof import('react-dom/server') & {
   default: typeof import('react-dom/server');
@@ -146,4 +148,37 @@ describe('render on the browser environment', () => {
     const element = createElement(undefined);
     await expect(render(element)).rejects.toThrowErrorMatchingSnapshot();
   });
+
+  it('passes render options to components wrapped with withRenderOptions', async () => {
+    type TemplateWithOptionsProps = { id: string };
+    const TemplateWithOptions = withRenderOptions<TemplateWithOptionsProps>(
+      (props) => {
+        return JSON.stringify(props);
+      },
+    );
+
+    const actualOutput = await render(
+      <TemplateWithOptions id="acbb4738-5a5e-4243-9b29-02cee9b8db57" />,
+      { plainText: true },
+    );
+
+    const expectedOutput =
+      '"{"id":"acbb4738-5a5e-4243-9b29-02cee9b8db57","renderOptions":{"plainText":true}}"';
+    expect(actualOutput).toMatchInlineSnapshot(expectedOutput);
+  });
+
+  it('does not pass render options to components not wrapped with withRenderOptions', async () => {
+    type TemplateWithOptionsProps = { id: string };
+    const TemplateWithOptions = (props: TemplateWithOptionsProps) => {
+      return JSON.stringify(props);
+    };
+
+    const actualOutput = await render(
+      <TemplateWithOptions id="acbb4738-5a5e-4243-9b29-02cee9b8db57" />,
+      { plainText: true },
+    );
+
+    const expectedOutput = '"{"id":"acbb4738-5a5e-4243-9b29-02cee9b8db57"}"';
+    expect(actualOutput).toMatchInlineSnapshot(expectedOutput);
+  });
 });
diff --git a/packages/render/src/browser/render.tsx b/packages/render/src/browser/render.tsx
@@ -4,6 +4,7 @@ import type { ReactDOMServerReadableStream } from 'react-dom/server';
 import { pretty } from '../node';
 import type { Options } from '../shared/options';
 import { plainTextSelectors } from '../shared/plain-text-selectors';
+import { injectRenderOptions } from '../shared/with-render-options';
 
 const decoder = new TextDecoder('utf-8');
 
@@ -39,7 +40,8 @@ const readStream = async (stream: ReactDOMServerReadableStream) => {
 };
 
 export const render = async (node: React.ReactNode, options?: Options) => {
-  const suspendedElement = <Suspense>{node}</Suspense>;
+  const nodeWithRenderOptionsProps = injectRenderOptions(node, options);
+  const suspendedElement = <Suspense>{nodeWithRenderOptionsProps}</Suspense>;
   const reactDOMServer = await import('react-dom/server.browser').then(
     // This is beacuse react-dom/server is CJS
     (m) => m.default,
diff --git a/packages/render/src/node/index.ts b/packages/render/src/node/index.ts
@@ -11,4 +11,5 @@ export const renderAsync = (element: React.ReactElement, options?: Options) => {
 export * from '../shared/options';
 export * from '../shared/plain-text-selectors';
 export * from '../shared/utils/pretty';
+export { type PropsWithRenderOptions, withRenderOptions } from '../shared/with-render-options';
 export * from './render';
diff --git a/packages/render/src/node/render-edge.spec.tsx b/packages/render/src/node/render-edge.spec.tsx
@@ -1,5 +1,7 @@
+import type { Options } from '../shared/options';
 import { Preview } from '../shared/utils/preview';
 import { Template } from '../shared/utils/template';
+import { withRenderOptions } from '../shared/with-render-options';
 import { render } from './render';
 
 type Import = typeof import('react-dom/server') & {
@@ -107,4 +109,37 @@ describe('render on the edge', () => {
       `"THIS SHOULD BE RENDERED IN PLAIN TEXT"`,
     );
   });
+
+
+  it('passes render options to components wrapped with withRenderOptions', async () => {
+    type TemplateWithOptionsProps = { id: string };
+    const TemplateWithOptions = withRenderOptions<TemplateWithOptionsProps>(
+      (props) => {
+        return JSON.stringify(props);
+      },
+    );
+
+    const actualOutput = await render(
+      <TemplateWithOptions id="acbb4738-5a5e-4243-9b29-02cee9b8db57" />,
+      { plainText: true },
+    );
+
+    const expectedOutput = '"{"id":"acbb4738-5a5e-4243-9b29-02cee9b8db57","renderOptions":{"plainText":true}}"'
+    expect(actualOutput).toMatchInlineSnapshot(expectedOutput);
+  });
+
+  it('does not pass render options to components not wrapped with withRenderOptions', async () => {
+    type TemplateWithOptionsProps = { id: string };
+    const TemplateWithOptions = (props: TemplateWithOptionsProps) => {
+      return JSON.stringify(props);
+    };
+
+    const actualOutput = await render(
+      <TemplateWithOptions id="acbb4738-5a5e-4243-9b29-02cee9b8db57" />,
+      { plainText: true },
+    );
+
+    const expectedOutput = '"{"id":"acbb4738-5a5e-4243-9b29-02cee9b8db57"}"'
+    expect(actualOutput).toMatchInlineSnapshot(expectedOutput);
+  });
 });
diff --git a/packages/render/src/node/render-node.spec.tsx b/packages/render/src/node/render-node.spec.tsx
@@ -4,9 +4,11 @@
 
 import { Suspense } from 'react';
 import usePromise from 'react-promise-suspense';
+import type { Options } from '../shared/options';
 import { Preview } from '../shared/utils/preview';
 import { Template } from '../shared/utils/template';
 import { render } from './render';
+import { withRenderOptions } from '../browser';
 
 type Import = typeof import('react-dom/server') & {
   default: typeof import('react-dom/server');
@@ -133,4 +135,37 @@ describe('render on node environments', () => {
       `"THIS SHOULD BE RENDERED IN PLAIN TEXT"`,
     );
   });
+
+  it('passes render options to components wrapped with withRenderOptions', async () => {
+    type TemplateWithOptionsProps = { id: string };
+    const TemplateWithOptions = withRenderOptions<TemplateWithOptionsProps>(
+      (props) => {
+        return JSON.stringify(props);
+      },
+    );
+
+    const actualOutput = await render(
+      <TemplateWithOptions id="acbb4738-5a5e-4243-9b29-02cee9b8db57" />,
+      { plainText: true },
+    );
+
+    const expectedOutput =
+      '"{"id":"acbb4738-5a5e-4243-9b29-02cee9b8db57","renderOptions":{"plainText":true}}"';
+    expect(actualOutput).toMatchInlineSnapshot(expectedOutput);
+  });
+
+  it('does not pass render options to components not wrapped with withRenderOptions', async () => {
+    type TemplateWithOptionsProps = { id: string };
+    const TemplateWithOptions = (props: TemplateWithOptionsProps) => {
+      return JSON.stringify(props);
+    };
+
+    const actualOutput = await render(
+      <TemplateWithOptions id="acbb4738-5a5e-4243-9b29-02cee9b8db57" />,
+      { plainText: true },
+    );
+
+    const expectedOutput = '"{"id":"acbb4738-5a5e-4243-9b29-02cee9b8db57"}"';
+    expect(actualOutput).toMatchInlineSnapshot(expectedOutput);
+  });
 });
diff --git a/packages/render/src/node/render.tsx b/packages/render/src/node/render.tsx
@@ -3,10 +3,12 @@ import { Suspense } from 'react';
 import type { Options } from '../shared/options';
 import { plainTextSelectors } from '../shared/plain-text-selectors';
 import { pretty } from '../shared/utils/pretty';
+import { injectRenderOptions } from '../shared/with-render-options';
 import { readStream } from './read-stream';
 
 export const render = async (node: React.ReactNode, options?: Options) => {
-  const suspendedElement = <Suspense>{node}</Suspense>;
+  const nodeWithRenderOptionsProps = injectRenderOptions(node, options);
+  const suspendedElement = <Suspense>{nodeWithRenderOptionsProps}</Suspense>;
   const reactDOMServer = await import('react-dom/server').then(
     // This is beacuse react-dom/server is CJS
     (m) => m.default,
diff --git a/packages/render/src/shared/with-render-options.tsx b/packages/render/src/shared/with-render-options.tsx
@@ -0,0 +1,76 @@
+import {
+  type ComponentType,
+  cloneElement,
+  isValidElement,
+  type ReactNode,
+} from 'react';
+import type { Options } from './options';
+
+const RENDER_OPTIONS_SYMBOL = Symbol.for('react-email.withRenderOptions');
+
+/** Extends component props with optional render options. */
+export type PropsWithRenderOptions<P = unknown> = P & {
+  renderOptions?: Options;
+};
+
+/** Component wrapped with withRenderOptions, marked with a symbol. */
+type ComponentWithRenderOptions<P = unknown> = ComponentType<
+  PropsWithRenderOptions<P>
+> & {
+  [RENDER_OPTIONS_SYMBOL]: true;
+};
+
+/**
+ * Wraps a component to receive render options as props.
+ *
+ * @param Component - The component to wrap.
+ * @return A component that accepts `renderOptions` prop.
+ *
+ * @example
+ * ```tsx
+ * export const EmailTemplate = withRenderOptions(({ renderOptions }) => {
+ *   if (renderOptions?.plainText) {
+ *     return 'Plain text version';
+ *   }
+ *   return <div><h1>HTML version</h1></div>;
+ * });
+ * ```
+ */
+export function withRenderOptions<P = unknown>(
+  Component: ComponentType<PropsWithRenderOptions<P>>,
+): ComponentWithRenderOptions<P> {
+  const WrappedComponent = Component as ComponentWithRenderOptions<P>;
+  WrappedComponent[RENDER_OPTIONS_SYMBOL] = true;
+  WrappedComponent.displayName = `withRenderOptions(${Component.displayName || Component.name || 'Component'})`;
+  return WrappedComponent;
+}
+
+/** @internal */
+function isWithRenderOptionsComponent(
+  component: unknown,
+): component is ComponentWithRenderOptions {
+  return (
+    !!component &&
+    typeof component === 'function' &&
+    RENDER_OPTIONS_SYMBOL in component &&
+    component[RENDER_OPTIONS_SYMBOL] === true
+  );
+}
+
+/**
+ * Injects render options into components wrapped with `withRenderOptions`.
+ * Returns node unchanged if not wrapped or not a valid element.
+ *
+ * @param node - The React node to inject options into.
+ * @param options - The render options to inject.
+ * @returns The node with injected options if applicable, otherwise the original node.
+ */
+export function injectRenderOptions(
+  node: ReactNode,
+  options?: Options,
+): ReactNode {
+  if (!isValidElement(node)) return node;
+  if (!isWithRenderOptionsComponent(node.type)) return node;
+  const renderOptionsProps = { renderOptions: options };
+  return cloneElement(node, renderOptionsProps);
+}
