feat(preview-server): error handling for prettier's invalid HTML error (#2265)

Author: gabrielmfern

.changeset/rare-fans-worry.md

@@ -0,0 +1,6 @@
+---
+"@react-email/preview-server": minor
+"react-email": minor
+---
+
+add custom error handling for prettier's syntax errors

packages/preview-server/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;

packages/preview-server/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',
 );

packages/preview-server/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,
+      },
     };
   }
 };

packages/preview-server/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!;

packages/preview-server/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>
+    </>
+  );
+};

packages/preview-server/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 ? (
           <>

packages/preview-server/src/app/preview/[...slug]/rendering-error.tsx

@@ -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;
   }