@react-email/preview-server 4.1.3 → 4.2.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @react-email/preview-server
 
+## 4.2.1
+
+### Patch Changes
+
+- c273405: pin all dependencies to avoid compatibility issues of the built preview server
+
+## 4.2.0
+
+### Minor Changes
+
+- e52818c: add custom error handling for prettier's syntax errors
+
 ## 4.1.3
 
 ### Patch Changes

package/jsx-runtime/jsx-dev-runtime.js

@@ -0,0 +1,24 @@
+// This hack is necessary because React forces the use of the non-dev JSX runtime
+// when NODE_ENV is set to 'production', which would break the data-source references
+// we need for stack traces in the preview server.
+const ReactJSXDevRuntime = require('react/jsx-dev-runtime');
+
+export function jsxDEV(type, props, key, isStaticChildren, source, self) {
+  const newProps = { ...props };
+
+  if (source && shouldIncludeSourceReference) {
+    newProps['data-source-file'] = source.fileName;
+    newProps['data-source-line'] = source.lineNumber;
+  }
+
+  return ReactJSXDevRuntime.jsxDEV(
+    type,
+    newProps,
+    key,
+    isStaticChildren,
+    source,
+    self,
+  );
+}
+
+export const Fragment = ReactJSXDevRuntime.Fragment;

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@react-email/preview-server",
-  "version": "4.1.3",
+  "version": "4.2.1",
   "description": "A live preview of your emails right in your browser.",
   "main": "./index.mjs",
   "dependencies": {
     "@babel/core": "7.26.10",
-    "@babel/parser": "^7.27.0",
-    "@babel/traverse": "^7.27.0",
+    "@babel/parser": "7.27.0",
+    "@babel/traverse": "7.27.0",
     "@lottiefiles/dotlottie-react": "0.13.3",
     "@radix-ui/colors": "3.0.0",
     "@radix-ui/react-collapsible": "1.1.7",
@@ -22,16 +22,16 @@
     "@types/react-dom": "19.0.4",
     "@types/webpack": "5.28.5",
     "autoprefixer": "10.4.21",
-    "chalk": "^4.1.2",
+    "chalk": "4.1.2",
     "clsx": "2.1.1",
-    "esbuild": "^0.25.0",
+    "esbuild": "0.25.0",
     "framer-motion": "12.7.5",
     "json5": "2.2.3",
-    "log-symbols": "^4.1.0",
+    "log-symbols": "4.1.0",
     "module-punycode": "npm:punycode@2.3.1",
-    "next": "^15.3.2",
+    "next": "15.4.1",
     "node-html-parser": "7.0.1",
-    "ora": "^5.4.1",
+    "ora": "5.4.1",
     "pretty-bytes": "6.1.1",
     "prism-react-renderer": "2.4.1",
     "react": "19.0.0",
@@ -61,7 +61,7 @@
     "postcss": "8.5.3",
     "tailwindcss": "3.4.0",
     "typescript": "5.8.3",
-    "@react-email/components": "0.3.0"
+    "@react-email/components": "0.3.1"
   },
   "license": "MIT",
   "repository": {

package/scripts/dev.mts

@@ -16,6 +16,7 @@ await fs.writeFile(
   `EMAILS_DIR_RELATIVE_PATH=./emails
 EMAILS_DIR_ABSOLUTE_PATH=${emailsDirectoryPath}
 USER_PROJECT_LOCATION=${previewServerRoot}
+PREVIEW_SERVER_LOCATION=${previewServerRoot}
 NEXT_PUBLIC_IS_PREVIEW_DEVELOPMENT=true`,
   'utf8',
 );

package/src/actions/render-email-by-path.tsx

@@ -4,14 +4,25 @@ import path from 'node:path';
 import chalk from 'chalk';
 import logSymbols from 'log-symbols';
 import ora, { type Ora } from 'ora';
-import { isBuilding, isPreviewDevelopment } from '../app/env';
+import {
+  isBuilding,
+  isPreviewDevelopment,
+  previewServerLocation,
+  userProjectLocation,
+} from '../app/env';
+import { convertStackWithSourceMap } from '../utils/convert-stack-with-sourcemap';
+import { createJsxRuntime } from '../utils/create-jsx-runtime';
 import { getEmailComponent } from '../utils/get-email-component';
-import { improveErrorWithSourceMap } from '../utils/improve-error-with-sourcemap';
 import { registerSpinnerAutostopping } from '../utils/register-spinner-autostopping';
 import type { ErrorObject } from '../utils/types/error-object';
 
 export interface RenderedEmailMetadata {
   markup: string;
+  /**
+   * HTML markup with `data-source-file` and `data-source-line` attributes pointing to the original
+   * .jsx/.tsx files corresponding to the rendered tag
+   */
+  markupWithReferences?: string;
   plainText: string;
   reactMarkup: string;
 }
@@ -44,7 +55,15 @@ export const renderEmailByPath = async (
     registerSpinnerAutostopping(spinner);
   }
 
-  const componentResult = await getEmailComponent(emailPath);
+  const originalJsxRuntimePath = path.resolve(
+    previewServerLocation,
+    'jsx-runtime',
+  );
+  const jsxRuntimePath = await createJsxRuntime(
+    userProjectLocation,
+    originalJsxRuntimePath,
+  );
+  const componentResult = await getEmailComponent(emailPath, jsxRuntimePath);
 
   if ('error' in componentResult) {
     spinner?.stopAndPersist({
@@ -58,21 +77,23 @@ export const renderEmailByPath = async (
     emailComponent: Email,
     createElement,
     render,
+    renderWithReferences,
     sourceMapToOriginalFile,
   } = componentResult;
 
   const previewProps = Email.PreviewProps || {};
   const EmailComponent = Email as React.FC;
   try {
-    const markup = await render(createElement(EmailComponent, previewProps), {
+    const element = createElement(EmailComponent, previewProps);
+    const markupWithReferences = await renderWithReferences(element, {
       pretty: true,
     });
-    const plainText = await render(
-      createElement(EmailComponent, previewProps),
-      {
-        plainText: true,
-      },
-    );
+    const markup = await render(element, {
+      pretty: true,
+    });
+    const plainText = await render(element, {
+      plainText: true,
+    });
 
     const reactMarkup = await fs.promises.readFile(emailPath, 'utf-8');
 
@@ -90,11 +111,12 @@ export const renderEmailByPath = async (
       text: `Successfully rendered ${emailFilename} in ${timeForConsole}`,
     });
 
-    const renderingResult = {
+    const renderingResult: RenderedEmailMetadata = {
       // This ensures that no null byte character ends up in the rendered
       // markup making users suspect of any issues. These null byte characters
       // only seem to happen with React 18, as it has no similar incident with React 19.
       markup: markup.replaceAll('\0', ''),
+      markupWithReferences: markupWithReferences.replaceAll('\0', ''),
       plainText,
       reactMarkup,
     };
@@ -110,12 +132,97 @@ export const renderEmailByPath = async (
       text: `Failed while rendering ${emailFilename}`,
     });
 
-    return {
-      error: improveErrorWithSourceMap(
-        error,
+    if (exception instanceof SyntaxError) {
+      interface SpanPosition {
+        file: {
+          content: string;
+        };
+        offset: number;
+        line: number;
+        col: number;
+      }
+      // means the email's HTML was invalid and prettier threw this error
+      // TODO: always throw when the HTML is invalid during `render`
+      const cause = exception.cause as {
+        msg: string;
+        span: {
+          start: SpanPosition;
+          end: SpanPosition;
+        };
+      };
+
+      const sourceFileAttributeMatches = cause.span.start.file.content.matchAll(
+        /data-source-file="(?<file>[^"]*)"/g,
+      );
+      let closestSourceFileAttribute: RegExpExecArray | undefined;
+      for (const sourceFileAttributeMatch of sourceFileAttributeMatches) {
+        if (closestSourceFileAttribute === undefined) {
+          closestSourceFileAttribute = sourceFileAttributeMatch;
+        }
+        if (
+          Math.abs(sourceFileAttributeMatch.index - cause.span.start.offset) <
+          Math.abs(closestSourceFileAttribute.index - cause.span.start.offset)
+        ) {
+          closestSourceFileAttribute = sourceFileAttributeMatch;
+        }
+      }
+
+      const findClosestAttributeValue = (
+        attributeName: string,
+      ): string | undefined => {
+        const attributeMatches = cause.span.start.file.content.matchAll(
+          new RegExp(`${attributeName}="(?<value>[^"]*)"`, 'g'),
+        );
+        let closestAttribute: RegExpExecArray | undefined;
+        for (const attributeMatch of attributeMatches) {
+          if (closestAttribute === undefined) {
+            closestAttribute = attributeMatch;
+          }
+          if (
+            Math.abs(attributeMatch.index - cause.span.start.offset) <
+            Math.abs(closestAttribute.index - cause.span.start.offset)
+          ) {
+            closestAttribute = attributeMatch;
+          }
+        }
+        return closestAttribute?.groups?.value;
+      };
+
+      let stack = convertStackWithSourceMap(
+        error.stack,
         emailPath,
         sourceMapToOriginalFile,
-      ),
+      );
+
+      const sourceFile = findClosestAttributeValue('data-source-file');
+      const sourceLine = findClosestAttributeValue('data-source-line');
+      if (sourceFile && sourceLine) {
+        stack = ` at ${sourceFile}:${sourceLine}\n${stack}`;
+      }
+
+      return {
+        error: {
+          name: exception.name,
+          message: cause.msg,
+          stack,
+          cause: error.cause ? JSON.parse(JSON.stringify(cause)) : undefined,
+        },
+      };
+    }
+
+    return {
+      error: {
+        name: error.name,
+        message: error.message,
+        stack: convertStackWithSourceMap(
+          error.stack,
+          emailPath,
+          sourceMapToOriginalFile,
+        ),
+        cause: error.cause
+          ? JSON.parse(JSON.stringify(error.cause))
+          : undefined,
+      },
     };
   }
 };

package/src/app/env.ts

@@ -5,6 +5,9 @@ export const emailsDirRelativePath = process.env.EMAILS_DIR_RELATIVE_PATH!;
 /** ONLY ACCESSIBLE ON THE SERVER */
 export const userProjectLocation = process.env.USER_PROJECT_LOCATION!;
 
+/** ONLY ACCESSIBLE ON THE SERVER */
+export const previewServerLocation = process.env.PREVIEW_SERVER_LOCATION!;
+
 /** ONLY ACCESSIBLE ON THE SERVER */
 export const emailsDirectoryAbsolutePath =
   process.env.EMAILS_DIR_ABSOLUTE_PATH!;

package/src/app/preview/[...slug]/error-overlay.tsx

@@ -0,0 +1,57 @@
+'use client';
+import type { ErrorObject } from '../../../utils/types/error-object';
+
+interface ErrorOverlayProps {
+  error: ErrorObject;
+}
+
+const Message = ({ children: content }: { children: string }) => {
+  const match = content.match(
+    /(Unexpected closing tag "[^"]+". It may happen when the tag has already been closed by another tag). (For more info see) (.+)/,
+  );
+  if (match) {
+    const [_, errorMessage, moreInfo, link] = match;
+    return (
+      <>
+        {errorMessage}.
+        <p className="text-lg">
+          {moreInfo}{' '}
+          <a className="underline" rel="noreferrer" target="_blank" href={link}>
+            {link}
+          </a>
+        </p>
+      </>
+    );
+  }
+  return content;
+};
+
+export const ErrorOverlay = ({ error }: ErrorOverlayProps) => {
+  return (
+    <>
+      <div className="absolute inset-0 z-50 bg-black/80" />
+      <div
+        className="
+        min-h-[50vh] w-full max-w-lg sm:rounded-lg md:max-w-[568px] lg:max-w-[920px]
+        absolute left-[50%] top-[50%] z-50  translate-x-[-50%] translate-y-[-50%] 
+        rounded-t-sm overflow-hidden bg-white text-black shadow-lg duration-200
+        flex flex-col selection:!text-black
+      "
+      >
+        <div className="bg-red-500 h-3" />
+        <div className="flex flex-grow p-6 min-w-0 max-w-full flex-col space-y-1.5">
+          <div className="flex-shrink pb-2 text-xl tracking-tight">
+            <b>{error.name}</b>: <Message>{error.message}</Message>
+          </div>
+          {error.stack ? (
+            <div className="flex-grow scroll-px-4 overflow-x-auto rounded-lg bg-black p-2 text-gray-100">
+              <pre className="w-full min-w-0 font-mono leading-6 selection:!text-cyan-12 text-xs">
+                {error.stack}
+              </pre>
+            </div>
+          ) : undefined}
+        </div>
+      </div>
+    </>
+  );
+};

package/src/app/preview/[...slug]/preview.tsx

@@ -19,7 +19,7 @@ import { ViewSizeControls } from '../../../components/topbar/view-size-controls'
 import { PreviewContext } from '../../../contexts/preview';
 import { useClampedState } from '../../../hooks/use-clamped-state';
 import { cn } from '../../../utils';
-import { RenderingError } from './rendering-error';
+import { ErrorOverlay } from './error-overlay';
 
 interface PreviewProps extends React.ComponentProps<'div'> {
   emailTitle: string;
@@ -136,7 +136,7 @@ const Preview = ({ emailTitle, className, ...props }: PreviewProps) => {
           };
         }}
       >
-        {hasErrors ? <RenderingError error={renderingResult.error} /> : null}
+        {hasErrors ? <ErrorOverlay error={renderingResult.error} /> : null}
 
         {hasRenderingMetadata ? (
           <>

package/src/utils/caniemail/tailwind/get-tailwind-config.ts

@@ -5,7 +5,7 @@ import * as esbuild from 'esbuild';
 import type { RawSourceMap } from 'source-map-js';
 import type { Config as TailwindOriginalConfig } from 'tailwindcss';
 import type { AST } from '../../../actions/email-validation/check-compatibility';
-import { improveErrorWithSourceMap } from '../../improve-error-with-sourcemap';
+import { convertStackWithSourceMap } from '../../convert-stack-with-sourcemap';
 import { isErr } from '../../result';
 import { runBundledCode } from '../../run-bundled-code';
 
@@ -101,15 +101,9 @@ export { reactEmailTailwindConfigInternal };`,
     sourceMap.sources = sourceMap.sources.map((source) =>
       path.resolve(sourceMapFile.path, '..', source),
     );
-    const errorObject = improveErrorWithSourceMap(
-      configModule.error as Error,
-      filepath,
-      sourceMap,
-    );
-    const error = new Error();
-    error.name = errorObject.name;
-    error.message = errorObject.message;
-    error.stack = errorObject.stack;
+
+    const error = configModule.error as Error;
+    error.stack = convertStackWithSourceMap(error.stack, filepath, sourceMap);
     throw error;
   }
 

package/src/utils/{improve-error-with-sourcemap.ts → convert-stack-with-sourcemap.ts}

@@ -1,14 +1,13 @@
 import path from 'node:path';
 import { type RawSourceMap, SourceMapConsumer } from 'source-map-js';
 import * as stackTraceParser from 'stacktrace-parser';
-import type { ErrorObject } from './types/error-object';
 
-export const improveErrorWithSourceMap = (
-  error: Error,
+export const convertStackWithSourceMap = (
+  rawStack: string | undefined,
 
   originalFilePath: string,
   sourceMapToOriginalFile: RawSourceMap,
-): ErrorObject => {
+): string | undefined => {
   let stack: string | undefined;
 
   const sourceRoot =
@@ -32,8 +31,8 @@ export const improveErrorWithSourceMap = (
         })`;
   };
 
-  if (typeof error.stack !== 'undefined') {
-    const parsedStack = stackTraceParser.parse(error.stack);
+  if (rawStack) {
+    const parsedStack = stackTraceParser.parse(rawStack);
     const sourceMapConsumer = new SourceMapConsumer(sourceMapToOriginalFile);
     const newStackLines = [] as string[];
     for (const stackFrame of parsedStack) {
@@ -77,9 +76,5 @@ export const improveErrorWithSourceMap = (
     stack = newStackLines.join('\n');
   }
 
-  return {
-    name: error.name,
-    message: error.message,
-    stack,
-  };
+  return stack;
 };

package/src/utils/create-jsx-runtime.ts

@@ -0,0 +1,37 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import esbuild from 'esbuild';
+
+/**
+ * Bundles the JSX runtime with the specified {@link cwd}. This is needed because the JSX runtime
+ * imports React's which is forcefully the production one if the `NODE_ENV` is set to `production`,
+ * even though we want to use the development one.
+ *
+ * It bundles into `/node_modules/.react-email-jsx-runtime` with the root being the {@link cwd}.
+ */
+export const createJsxRuntime = async (
+  cwd: string,
+  originalJsxRuntimePath: string,
+) => {
+  const jsxRuntimePath = path.join(
+    cwd,
+    'node_modules',
+    '.react-email-jsx-runtime',
+  );
+  await esbuild.build({
+    bundle: true,
+    outfile: path.join(jsxRuntimePath, 'jsx-dev-runtime.js'),
+    format: 'cjs',
+    logLevel: 'silent',
+    stdin: {
+      resolveDir: cwd,
+      sourcefile: 'jsx-dev-runtime.js',
+      loader: 'js',
+      contents: await fs.promises.readFile(
+        path.join(originalJsxRuntimePath, 'jsx-dev-runtime.js'),
+      ),
+    },
+  });
+
+  return jsxRuntimePath;
+};

package/src/utils/get-email-component.spec.ts

@@ -6,6 +6,7 @@ describe('getEmailComponent()', () => {
     test('Request', async () => {
       const result = await getEmailComponent(
         path.resolve(__dirname, './testing/request-response-email.tsx'),
+        path.resolve(__dirname, '../../jsx-runtime'),
       );
       if ('error' in result) {
         console.log(result.error);
@@ -20,6 +21,7 @@ describe('getEmailComponent()', () => {
         __dirname,
         '../../../../apps/demo/emails/notifications/vercel-invite-user.tsx',
       ),
+      path.resolve(__dirname, '../../jsx-runtime'),
     );
 
     if ('error' in result) {

package/src/utils/get-email-component.ts

@@ -4,10 +4,10 @@ import { type BuildFailure, build, type OutputFile } from 'esbuild';
 import type React from 'react';
 import type { RawSourceMap } from 'source-map-js';
 import { z } from 'zod';
+import { convertStackWithSourceMap } from './convert-stack-with-sourcemap';
 import { renderingUtilitiesExporter } from './esbuild/renderring-utilities-exporter';
-import { improveErrorWithSourceMap } from './improve-error-with-sourcemap';
 import { isErr } from './result';
-import { runBundledCode } from './run-bundled-code';
+import { createContext, runBundledCode } from './run-bundled-code';
 import type { EmailTemplate as EmailComponent } from './types/email-template';
 import type { ErrorObject } from './types/error-object';
 
@@ -19,12 +19,18 @@ const EmailComponentModule = z.object({
 
 export const getEmailComponent = async (
   emailPath: string,
+  jsxRuntimePath: string,
 ): Promise<
   | {
       emailComponent: EmailComponent;
 
       createElement: typeof React.createElement;
 
+      /**
+       * Renders the HTML with `data-source-file`/`data-source-line` attributes that should only be
+       * used internally in the preview server and never shown to the user.
+       */
+      renderWithReferences: typeof render;
       render: typeof render;
 
       sourceMapToOriginalFile: RawSourceMap;
@@ -40,6 +46,9 @@ export const getEmailComponent = async (
       platform: 'node',
       write: false,
 
+      jsxDev: true,
+      jsxImportSource: jsxRuntimePath,
+
       format: 'cjs',
       jsx: 'automatic',
       logLevel: 'silent',
@@ -74,7 +83,9 @@ export const getEmailComponent = async (
     path.resolve(sourceMapFile.path, '..', source),
   );
 
-  const runningResult = runBundledCode(builtEmailCode, emailPath);
+  const context = createContext(emailPath);
+  context.shouldIncludeSourceReference = false;
+  const runningResult = runBundledCode(builtEmailCode, emailPath, context);
 
   if (isErr(runningResult)) {
     const { error } = runningResult;
@@ -82,7 +93,16 @@ export const getEmailComponent = async (
       error.stack &&= error.stack.split('at Script.runInContext (node:vm')[0];
 
       return {
-        error: improveErrorWithSourceMap(error, emailPath, sourceMapToEmail),
+        error: {
+          name: error.name,
+          message: error.message,
+          stack: convertStackWithSourceMap(
+            error.stack,
+            emailPath,
+            sourceMapToEmail,
+          ),
+          cause: error.cause,
+        },
       };
     }
 
@@ -93,31 +113,23 @@ export const getEmailComponent = async (
 
   if (parseResult.error) {
     return {
-      error: improveErrorWithSourceMap(
-        new Error(
-          `The email component at ${emailPath} does not contain the expected exports`,
-          {
-            cause: parseResult.error,
-          },
-        ),
-        emailPath,
-        sourceMapToEmail,
-      ),
+      error: {
+        name: 'Error',
+        message: `The email component at ${emailPath} does not contain the expected exports`,
+        stack: new Error().stack,
+        cause: parseResult.error,
+      },
     };
   }
 
   if (typeof parseResult.data.default !== 'function') {
     return {
-      error: improveErrorWithSourceMap(
-        new Error(
-          `The email component at ${emailPath} does not contain a default exported function`,
-          {
-            cause: parseResult.error,
-          },
-        ),
-        emailPath,
-        sourceMapToEmail,
-      ),
+      error: {
+        name: 'Error',
+        message: `The email component at ${emailPath} does not contain a default exported function`,
+        stack: new Error().stack,
+        cause: parseResult.error,
+      },
     };
   }
 
@@ -125,6 +137,12 @@ export const getEmailComponent = async (
 
   return {
     emailComponent: componentModule.default as EmailComponent,
+    renderWithReferences: (async (...args) => {
+      context.shouldIncludeSourceReference = true;
+      const renderingResult = await componentModule.render(...args);
+      context.shouldIncludeSourceReference = false;
+      return renderingResult;
+    }) as typeof render,
     render: componentModule.render as typeof render,
     createElement:
       componentModule.reactEmailCreateReactElement as typeof React.createElement,

package/src/utils/run-bundled-code.ts

@@ -3,11 +3,8 @@ import vm from 'node:vm';
 import { err, ok, type Result } from './result';
 import { staticNodeModulesForVM } from './static-node-modules-for-vm';
 
-export const runBundledCode = (
-  code: string,
-  filename: string,
-): Result<unknown, unknown> => {
-  const fakeContext = {
+export const createContext = (filename: string): vm.Context => {
+  return {
     ...global,
     console,
     Buffer,
@@ -18,6 +15,8 @@ export const runBundledCode = (
     Request,
     Response,
     TextDecoderStream,
+    SyntaxError,
+    Error,
     TextEncoder,
     TextEncoderStream,
     ReadableStream,
@@ -53,7 +52,13 @@ export const runBundledCode = (
     },
     process,
   };
+};
 
+export const runBundledCode = (
+  code: string,
+  filename: string,
+  fakeContext: vm.Context = createContext(filename),
+): Result<unknown, unknown> => {
   try {
     vm.runInNewContext(code, fakeContext, { filename });
   } catch (exception) {