@react-email/preview-server 4.1.2 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @react-email/preview-server
 
+## 4.2.0
+
+### Minor Changes
+
+- e52818c: add custom error handling for prettier's syntax errors
+
+## 4.1.3
+
+### Patch Changes
+
+- 09d7d9d: improved method of resolving tailwind configs when checking compatibility
+
 ## 4.1.2
 
 ### 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,6 +1,6 @@
 {
   "name": "@react-email/preview-server",
-  "version": "4.1.2",
+  "version": "4.2.0",
   "description": "A live preview of your emails right in your browser.",
   "main": "./index.mjs",
   "dependencies": {
@@ -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.spec.ts

@@ -0,0 +1,44 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { parse } from '@babel/parser';
+import { pixelBasedPreset } from '@react-email/components';
+import { getTailwindConfig } from './get-tailwind-config';
+
+describe('getTailwindConfig()', () => {
+  it("should work on the demo's Vercel Invite template", async () => {
+    const sourcePath = path.resolve(
+      __dirname,
+      '../../../../../../apps/demo/emails/notifications/vercel-invite-user.tsx',
+    );
+    const sourceCode = await fs.readFile(sourcePath, 'utf8');
+    const ast = parse(sourceCode, {
+      strictMode: false,
+      errorRecovery: true,
+      sourceType: 'unambiguous',
+      plugins: ['jsx', 'typescript', 'decorators'],
+    });
+
+    expect(await getTailwindConfig(sourceCode, ast, sourcePath)).toEqual({
+      presets: [pixelBasedPreset],
+    });
+  });
+
+  it('should work with email templates that import the tailwind config', async () => {
+    const sourcePath = path.resolve(
+      __dirname,
+      './tests/dummy-email-template.tsx',
+    );
+    const sourceCode = await fs.readFile(sourcePath, 'utf8');
+    const ast = parse(sourceCode, {
+      strictMode: false,
+      errorRecovery: true,
+      sourceType: 'unambiguous',
+      plugins: ['jsx', 'typescript', 'decorators'],
+    });
+
+    expect(await getTailwindConfig(sourceCode, ast, sourcePath)).toEqual({
+      theme: {},
+      presets: [pixelBasedPreset],
+    });
+  });
+});

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

@@ -2,8 +2,10 @@ import path from 'node:path';
 import type { Node } from '@babel/traverse';
 import traverse from '@babel/traverse';
 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 { convertStackWithSourceMap } from '../../convert-stack-with-sourcemap';
 import { isErr } from '../../result';
 import { runBundledCode } from '../../run-bundled-code';
 
@@ -23,8 +25,6 @@ export type TailwindConfig = Pick<
   | 'plugins'
 >;
 
-type ImportDeclaration = Node & { type: 'ImportDeclaration' };
-
 export const getTailwindConfig = async (
   sourceCode: string,
   ast: AST,
@@ -33,35 +33,23 @@ export const getTailwindConfig = async (
   const configAttribute = getTailwindConfigNode(ast);
 
   if (configAttribute) {
-    const configIdentifierName =
-      configAttribute.value?.type === 'JSXExpressionContainer' &&
-      configAttribute.value.expression.type === 'Identifier'
-        ? configAttribute.value.expression.name
-        : undefined;
-    if (configIdentifierName) {
-      const tailwindConfigImport = getImportWithGivenDefaultSpecifier(
-        ast,
-        configIdentifierName,
-      );
-      if (tailwindConfigImport) {
-        return getConfigFromImport(tailwindConfigImport, sourcePath);
-      }
-    }
-
-    const configObjectExpression =
-      configAttribute.value?.type === 'JSXExpressionContainer' &&
-      configAttribute.value.expression.type === 'ObjectExpression'
+    const configExpressionValue =
+      configAttribute.value?.type === 'JSXExpressionContainer'
         ? configAttribute.value.expression
         : undefined;
-    if (configObjectExpression?.start && configObjectExpression.end) {
-      const configObjectSourceCode = sourceCode.slice(
-        configObjectExpression.start,
-        configObjectExpression.end,
+    if (configExpressionValue?.start && configExpressionValue.end) {
+      const configSourceValue = sourceCode.slice(
+        configExpressionValue.start,
+        configExpressionValue.end,
       );
 
       try {
-        const getConfig = new Function(`return ${configObjectSourceCode}`);
-        return getConfig() as TailwindConfig;
+        return getConfigFromCode(
+          `${sourceCode}
+
+const reactEmailTailwindConfigInternal = ${configSourceValue};`,
+          sourcePath,
+        );
       } catch (exception) {
         console.warn(exception);
         console.warn(
@@ -74,80 +62,71 @@ export const getTailwindConfig = async (
   return {};
 };
 
-const getConfigFromImport = async (
-  tailwindConfigImport: ImportDeclaration,
-  sourcePath: string,
+const getConfigFromCode = async (
+  code: string,
+  filepath: string,
 ): Promise<TailwindConfig> => {
-  const configRelativePath = tailwindConfigImport.source.value;
-  const sourceDirpath = path.dirname(sourcePath);
-  const configFilepath = path.join(sourceDirpath, configRelativePath);
+  const configDirpath = path.dirname(filepath);
 
   const configBuildResult = await esbuild.build({
     bundle: true,
     stdin: {
-      contents: `import tailwindConfig from "${configRelativePath}"; 
-export { tailwindConfig };`,
+      contents: `${code} 
+export { reactEmailTailwindConfigInternal };`,
+      sourcefile: filepath,
       loader: 'tsx',
-      resolveDir: path.dirname(sourcePath),
+      resolveDir: configDirpath,
     },
     platform: 'node',
+    sourcemap: 'external',
+    jsx: 'automatic',
+    outdir: 'stdout', // just a stub for esbuild, it won't actually write to this folder
     write: false,
     format: 'cjs',
     logLevel: 'silent',
   });
-  const configFile = configBuildResult.outputFiles[0];
+  const sourceMapFile = configBuildResult.outputFiles[0]!;
+  const configFile = configBuildResult.outputFiles[1];
   if (configFile === undefined) {
     throw new Error(
       'Could not build config file as it was found as undefined, this is most likely a bug, please open an issue.',
     );
   }
-  const configModule = runBundledCode(configFile.text, configFilepath);
+
+  const configModule = runBundledCode(configFile.text, filepath);
   if (isErr(configModule)) {
-    throw new Error(
-      `Error when trying to run the config file: ${configModule.error}`,
+    const sourceMap = JSON.parse(sourceMapFile.text) as RawSourceMap;
+    // because it will have a path like <tsconfigLocation>/stdout/email.js.map
+    sourceMap.sourceRoot = path.resolve(sourceMapFile.path, '../..');
+    sourceMap.sources = sourceMap.sources.map((source) =>
+      path.resolve(sourceMapFile.path, '..', source),
     );
+
+    const error = configModule.error as Error;
+    error.stack = convertStackWithSourceMap(error.stack, filepath, sourceMap);
+    throw error;
   }
 
   if (
     typeof configModule.value === 'object' &&
     configModule.value !== null &&
-    'tailwindConfig' in configModule.value
+    'reactEmailTailwindConfigInternal' in configModule.value
   ) {
-    return configModule.value.tailwindConfig as TailwindConfig;
+    return configModule.value
+      .reactEmailTailwindConfigInternal as TailwindConfig;
   }
 
   throw new Error(
-    `Could not read Tailwind config at ${configFilepath} because it doesn't have a default export in it.`,
+    'Could not get the Tailwind config, this is likely a bug, please file an issue.',
     {
       cause: {
         configModule,
-        configFilepath,
+        configFilepath: filepath,
       },
     },
   );
 };
 
-const getImportWithGivenDefaultSpecifier = (
-  ast: AST,
-  specifierName: string,
-) => {
-  let importNode: ImportDeclaration | undefined;
-  traverse(ast, {
-    ImportDeclaration(nodePath) {
-      if (
-        nodePath.node.specifiers.some(
-          (specifier) =>
-            specifier.type === 'ImportDefaultSpecifier' &&
-            specifier.local.name === specifierName,
-        )
-      ) {
-        importNode = nodePath.node;
-      }
-    },
-  });
-  return importNode;
-};
-
 type JSXAttribute = Node & { type: 'JSXAttribute' };
 
 const getTailwindConfigNode = (ast: AST) => {

package/src/utils/caniemail/tailwind/tests/dummy-email-template.tsx

@@ -0,0 +1,10 @@
+import { Tailwind } from '@react-email/components';
+import tailwindConfig from './tailwind.config';
+
+export default function EmailTemplate() {
+  return (
+    <Tailwind config={tailwindConfig}>
+      <div className="bg-red-400 w-20" />
+    </Tailwind>
+  );
+}

package/src/utils/caniemail/tailwind/tests/tailwind.config.ts

@@ -0,0 +1,6 @@
+import { pixelBasedPreset, type TailwindConfig } from '@react-email/components';
+
+export default {
+  theme: {},
+  presets: [pixelBasedPreset],
+} satisfies TailwindConfig;

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