@react-email/preview-server 1.0.0-canary.0

package/src/utils/contains-email-template.spec.ts

@@ -0,0 +1,124 @@
+import {
+  containsEmailTemplate,
+  removeFilenameExtension,
+} from './contains-email-template';
+import type { EmailsDirectory } from './get-emails-directory-metadata';
+
+describe('removeFilenameExtension()', () => {
+  it('should work with a single .', () => {
+    expect(removeFilenameExtension('email-template.tsx')).toBe(
+      'email-template',
+    );
+  });
+
+  it('should work with an example test file', () => {
+    expect(removeFilenameExtension('email-template.spec.tsx')).toBe(
+      'email-template.spec',
+    );
+  });
+
+  it('should do nothing when there is no extension', () => {
+    expect(removeFilenameExtension('email-template')).toBe('email-template');
+  });
+});
+
+describe('containsEmailTemplate()', () => {
+  const directory: EmailsDirectory = {
+    absolutePath: '/fake/path/emails',
+    directoryName: 'emails',
+    relativePath: '',
+    emailFilenames: [],
+    subDirectories: [
+      {
+        absolutePath: '/fake/path/emails/magic-links',
+        directoryName: 'magic-links',
+        relativePath: 'magic-links',
+        emailFilenames: [
+          'aws-verify-email',
+          'linear-login-code',
+          'notion-magic-link',
+          'plaid-verify-identity',
+          'raycast-magic-link',
+          'slack-confirm',
+        ],
+        subDirectories: [
+          {
+            absolutePath: '/fake/path/emails/magic-links/resend',
+            directoryName: 'resend',
+            emailFilenames: ['verify-email'],
+            relativePath: 'magic-links/resend',
+            subDirectories: [],
+          },
+        ],
+      },
+      {
+        absolutePath: '/fake/path/emails/newsletters',
+        directoryName: 'newsletters',
+        relativePath: 'newsletters',
+        emailFilenames: [
+          'codepen-challengers',
+          'google-play-policy-update',
+          'stack-overflow-tips',
+        ],
+        subDirectories: [],
+      },
+      {
+        absolutePath: '/fake/path/emails/notifications',
+        directoryName: 'notifications',
+        relativePath: 'notifications',
+        emailFilenames: [
+          'github-access-token',
+          'papermark-year-in-review',
+          'vercel-invite-user',
+          'yelp-recent-login',
+        ],
+        subDirectories: [],
+      },
+      {
+        absolutePath: '/fake/path/emails/receipts',
+        directoryName: 'receipts',
+        relativePath: 'receipts',
+        emailFilenames: ['apple-receipt', 'nike-receipt'],
+        subDirectories: [],
+      },
+      {
+        absolutePath: '/fake/path/emails/reset-password',
+        directoryName: 'reset-password',
+        relativePath: 'reset-password',
+        emailFilenames: ['dropbox-reset-password', 'twitch-reset-password'],
+        subDirectories: [],
+      },
+      {
+        absolutePath: '/fake/path/emails/reviews',
+        directoryName: 'reviews',
+        relativePath: 'reviews',
+        emailFilenames: ['airbnb-review', 'amazon-review'],
+        subDirectories: [],
+      },
+      {
+        absolutePath: '/fake/path/emails/welcome',
+        directoryName: 'welcome',
+        relativePath: 'welcome',
+        emailFilenames: ['koala-welcome', 'netlify-welcome', 'stripe-welcome'],
+        subDirectories: [],
+      },
+    ],
+  };
+  it('should work with email inside a single sub directory', () => {
+    expect(containsEmailTemplate('welcome/koala-welcome', directory)).toBe(
+      true,
+    );
+    expect(containsEmailTemplate('welcome/missing-template', directory)).toBe(
+      false,
+    );
+  });
+
+  it('should work with email inside a second sub directory', () => {
+    expect(
+      containsEmailTemplate('magic-links/resend/verify-email', directory),
+    ).toBe(true);
+    expect(
+      containsEmailTemplate('magic-links/resend/missing-template', directory),
+    ).toBe(false);
+  });
+});

package/src/utils/contains-email-template.ts

@@ -0,0 +1,33 @@
+import type { EmailsDirectory } from './get-emails-directory-metadata';
+
+export const removeFilenameExtension = (filename: string): string => {
+  const parts = filename.split('.');
+
+  if (parts.length > 1) {
+    return parts.slice(0, -1).join('.');
+  }
+
+  return filename;
+};
+
+export const containsEmailTemplate = (
+  relativeEmailPath: string,
+  directory: EmailsDirectory,
+) => {
+  const remainingSegments = relativeEmailPath
+    .replace(directory.relativePath, '')
+    .split('/')
+    .filter(Boolean);
+  if (remainingSegments.length === 1) {
+    const emailFilename = removeFilenameExtension(remainingSegments[0]!);
+    return directory.emailFilenames.includes(emailFilename);
+  }
+  const subDirectory = directory.subDirectories.find(
+    (sub) => sub.directoryName === remainingSegments[0],
+  );
+  if (subDirectory === undefined) {
+    return false;
+  }
+
+  return containsEmailTemplate(relativeEmailPath, subDirectory);
+};

package/src/utils/copy-text-to-clipboard.ts

@@ -0,0 +1,7 @@
+export const copyTextToClipboard = async (text: string) => {
+  try {
+    await navigator.clipboard.writeText(text);
+  } catch {
+    throw new Error('Not able to copy');
+  }
+};

package/src/utils/esbuild/escape-string-for-regex.ts

@@ -0,0 +1,3 @@
+export function escapeStringForRegex(string: string) {
+  return string.replace(/[|\\{}()[\]^$+*?.]/g, '\\$&').replace(/-/g, '\\x2d');
+}

package/src/utils/esbuild/renderring-utilities-exporter.ts

@@ -0,0 +1,63 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import type { Loader, PluginBuild, ResolveOptions } from 'esbuild';
+import { escapeStringForRegex } from './escape-string-for-regex';
+
+/**
+ * Made to export the `render` function out of the user's email template
+ * so that issues like https://github.com/resend/react-email/issues/649 don't
+ * happen.
+ *
+ * This also exports the `createElement` from the user's React version as well
+ * to avoid mismatches.
+ *
+ * This avoids multiple versions of React being involved, i.e., the version
+ * in the CLI vs. the version the user has on their emails.
+ */
+export const renderingUtilitiesExporter = (emailTemplates: string[]) => ({
+  name: 'rendering-utilities-exporter',
+  setup: (b: PluginBuild) => {
+    b.onLoad(
+      {
+        filter: new RegExp(
+          emailTemplates
+            .map((emailPath) => escapeStringForRegex(emailPath))
+            .join('|'),
+        ),
+      },
+      async ({ path: pathToFile }) => {
+        return {
+          contents: `${await fs.readFile(pathToFile, 'utf8')};
+          export { render } from 'react-email-module-that-will-export-render'
+          export { createElement as reactEmailCreateReactElement } from 'react';
+        `,
+          loader: path.extname(pathToFile).slice(1) as Loader,
+        };
+      },
+    );
+
+    b.onResolve(
+      { filter: /^react-email-module-that-will-export-render$/ },
+      async (args) => {
+        const options: ResolveOptions = {
+          kind: 'import-statement',
+          importer: args.importer,
+          resolveDir: args.resolveDir,
+          namespace: args.namespace,
+        };
+        let result = await b.resolve('@react-email/render', options);
+        if (result.errors.length === 0) {
+          return result;
+        }
+
+        // If @react-email/render does not exist, resolve to @react-email/components
+        result = await b.resolve('@react-email/components', options);
+        if (result.errors.length > 0 && result.errors[0]) {
+          result.errors[0].text =
+            "Failed trying to import `render` from either `@react-email/render` or `@react-email/components` to be able to render your email template.\n Maybe you don't have either of them installed?";
+        }
+        return result;
+      },
+    );
+  },
+});

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

@@ -0,0 +1,41 @@
+import path from 'node:path';
+import { getEmailComponent } from './get-email-component';
+
+describe('getEmailComponent()', () => {
+  describe('Node internals support', () => {
+    test('Request', async () => {
+      const result = await getEmailComponent(
+        path.resolve(__dirname, './testing/request-response-email.tsx'),
+      );
+      if ('error' in result) {
+        console.log(result.error);
+        expect('error' in result, 'there should be no errors').toBe(false);
+      }
+    });
+  });
+
+  test('with a demo email template', async () => {
+    const result = await getEmailComponent(
+      path.resolve(
+        __dirname,
+        '../../../../apps/demo/emails/notifications/vercel-invite-user.tsx',
+      ),
+    );
+
+    if ('error' in result) {
+      console.log(result.error);
+      expect('error' in result).toBe(false);
+    } else {
+      expect(result.emailComponent).toBeTruthy();
+      expect(result.sourceMapToOriginalFile).toBeTruthy();
+
+      const emailHtml = await result.render(
+        result.createElement(
+          result.emailComponent,
+          result.emailComponent.PreviewProps,
+        ),
+      );
+      expect(emailHtml).toMatchSnapshot();
+    }
+  });
+});

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

@@ -0,0 +1,134 @@
+import path from 'node:path';
+import type { render } from '@react-email/components';
+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 { renderingUtilitiesExporter } from './esbuild/renderring-utilities-exporter';
+import { improveErrorWithSourceMap } from './improve-error-with-sourcemap';
+import { isErr } from './result';
+import { runBundledCode } from './run-bundled-code';
+import type { EmailTemplate as EmailComponent } from './types/email-template';
+import type { ErrorObject } from './types/error-object';
+
+const EmailComponentModule = z.object({
+  default: z.any(),
+  render: z.function(),
+  reactEmailCreateReactElement: z.function(),
+});
+
+export const getEmailComponent = async (
+  emailPath: string,
+): Promise<
+  | {
+      emailComponent: EmailComponent;
+
+      createElement: typeof React.createElement;
+
+      render: typeof render;
+
+      sourceMapToOriginalFile: RawSourceMap;
+    }
+  | { error: ErrorObject }
+> => {
+  let outputFiles: OutputFile[];
+  try {
+    const buildData = await build({
+      bundle: true,
+      entryPoints: [emailPath],
+      plugins: [renderingUtilitiesExporter([emailPath])],
+      platform: 'node',
+      write: false,
+
+      format: 'cjs',
+      jsx: 'automatic',
+      logLevel: 'silent',
+      // allows for using jsx on a .js file
+      loader: {
+        '.js': 'jsx',
+      },
+      outdir: 'stdout', // just a stub for esbuild, it won't actually write to this folder
+      sourcemap: 'external',
+    });
+    outputFiles = buildData.outputFiles;
+  } catch (exception) {
+    const buildFailure = exception as BuildFailure;
+    return {
+      error: {
+        message: buildFailure.message,
+        stack: buildFailure.stack,
+        name: buildFailure.name,
+        cause: buildFailure.cause,
+      },
+    };
+  }
+
+  const sourceMapFile = outputFiles[0]!;
+  const bundledEmailFile = outputFiles[1]!;
+  const builtEmailCode = bundledEmailFile.text;
+
+  const sourceMapToEmail = JSON.parse(sourceMapFile.text) as RawSourceMap;
+  // because it will have a path like <tsconfigLocation>/stdout/email.js.map
+  sourceMapToEmail.sourceRoot = path.resolve(sourceMapFile.path, '../..');
+  sourceMapToEmail.sources = sourceMapToEmail.sources.map((source) =>
+    path.resolve(sourceMapFile.path, '..', source),
+  );
+
+  const runningResult = runBundledCode(builtEmailCode, emailPath);
+
+  if (isErr(runningResult)) {
+    const { error } = runningResult;
+    if (error instanceof Error) {
+      error.stack &&= error.stack.split('at Script.runInContext (node:vm')[0];
+
+      return {
+        error: improveErrorWithSourceMap(error, emailPath, sourceMapToEmail),
+      };
+    }
+
+    throw error;
+  }
+
+  const parseResult = EmailComponentModule.safeParse(runningResult.value);
+
+  if (parseResult.error) {
+    return {
+      error: improveErrorWithSourceMap(
+        new Error(
+          `The email component at ${emailPath} does not contain the expected exports`,
+          {
+            cause: parseResult.error,
+          },
+        ),
+        emailPath,
+        sourceMapToEmail,
+      ),
+    };
+  }
+
+  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,
+      ),
+    };
+  }
+
+  const { data: componentModule } = parseResult;
+
+  return {
+    emailComponent: componentModule.default as EmailComponent,
+    render: componentModule.render as typeof render,
+    createElement:
+      componentModule.reactEmailCreateReactElement as typeof React.createElement,
+
+    sourceMapToOriginalFile: sourceMapToEmail,
+  };
+};

package/src/utils/get-emails-directory-metadata.spec.ts

@@ -0,0 +1,82 @@
+import path from 'node:path';
+import { getEmailsDirectoryMetadata } from './get-emails-directory-metadata';
+
+test('getEmailsDirectoryMetadata on demo emails', async () => {
+  const emailsDirectoryPath = path.resolve(
+    __dirname,
+    '../../../../apps/demo/emails',
+  );
+  expect(await getEmailsDirectoryMetadata(emailsDirectoryPath)).toEqual({
+    absolutePath: emailsDirectoryPath,
+    directoryName: 'emails',
+    relativePath: '',
+    emailFilenames: [],
+    subDirectories: [
+      {
+        absolutePath: `${emailsDirectoryPath}/magic-links`,
+        directoryName: 'magic-links',
+        relativePath: 'magic-links',
+        emailFilenames: [
+          'aws-verify-email',
+          'linear-login-code',
+          'notion-magic-link',
+          'plaid-verify-identity',
+          'raycast-magic-link',
+          'slack-confirm',
+        ],
+        subDirectories: [],
+      },
+      {
+        absolutePath: `${emailsDirectoryPath}/newsletters`,
+        directoryName: 'newsletters',
+        relativePath: 'newsletters',
+        emailFilenames: [
+          'codepen-challengers',
+          'google-play-policy-update',
+          'stack-overflow-tips',
+        ],
+        subDirectories: [],
+      },
+      {
+        absolutePath: `${emailsDirectoryPath}/notifications`,
+        directoryName: 'notifications',
+        relativePath: 'notifications',
+        emailFilenames: [
+          'github-access-token',
+          'papermark-year-in-review',
+          'vercel-invite-user',
+          'yelp-recent-login',
+        ],
+        subDirectories: [],
+      },
+      {
+        absolutePath: `${emailsDirectoryPath}/receipts`,
+        directoryName: 'receipts',
+        relativePath: 'receipts',
+        emailFilenames: ['apple-receipt', 'nike-receipt'],
+        subDirectories: [],
+      },
+      {
+        absolutePath: `${emailsDirectoryPath}/reset-password`,
+        directoryName: 'reset-password',
+        relativePath: 'reset-password',
+        emailFilenames: ['dropbox-reset-password', 'twitch-reset-password'],
+        subDirectories: [],
+      },
+      {
+        absolutePath: `${emailsDirectoryPath}/reviews`,
+        directoryName: 'reviews',
+        relativePath: 'reviews',
+        emailFilenames: ['airbnb-review', 'amazon-review'],
+        subDirectories: [],
+      },
+      {
+        absolutePath: `${emailsDirectoryPath}/welcome`,
+        directoryName: 'welcome',
+        relativePath: 'welcome',
+        emailFilenames: ['koala-welcome', 'netlify-welcome', 'stripe-welcome'],
+        subDirectories: [],
+      },
+    ],
+  });
+});

package/src/utils/get-emails-directory-metadata.ts

@@ -0,0 +1,141 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const isFileAnEmail = async (fullPath: string): Promise<boolean> => {
+  let fileHandle: fs.promises.FileHandle;
+  try {
+    fileHandle = await fs.promises.open(fullPath, 'r');
+  } catch (exception) {
+    console.warn(exception);
+    return false;
+  }
+  const stat = await fileHandle.stat();
+
+  if (stat.isDirectory()) {
+    await fileHandle.close();
+    return false;
+  }
+
+  const { ext } = path.parse(fullPath);
+
+  if (!['.js', '.tsx', '.jsx'].includes(ext)) {
+    await fileHandle.close();
+    return false;
+  }
+
+  // check with a heuristic to see if the file has at least
+  // a default export (ES6) or module.exports (CommonJS) or named exports (MDX)
+  const fileContents = await fileHandle.readFile('utf8');
+
+  await fileHandle.close();
+
+  // Check for ES6 export default syntax
+  const hasES6DefaultExport = /\bexport\s+default\b/gm.test(fileContents);
+
+  // Check for CommonJS module.exports syntax
+  const hasCommonJSExport = /\bmodule\.exports\s*=/gm.test(fileContents);
+
+  // Check for named exports (used in MDX files) and ensure at least one is marked as default
+  const hasNamedExport = /\bexport\s+\{[^}]*\bdefault\b[^}]*\}/gm.test(
+    fileContents,
+  );
+
+  return hasES6DefaultExport || hasCommonJSExport || hasNamedExport;
+};
+
+export interface EmailsDirectory {
+  absolutePath: string;
+  relativePath: string;
+  directoryName: string;
+  emailFilenames: string[];
+  subDirectories: EmailsDirectory[];
+}
+
+const mergeDirectoriesWithSubDirectories = (
+  emailsDirectoryMetadata: EmailsDirectory,
+): EmailsDirectory => {
+  let currentResultingMergedDirectory: EmailsDirectory =
+    emailsDirectoryMetadata;
+
+  while (
+    currentResultingMergedDirectory.emailFilenames.length === 0 &&
+    currentResultingMergedDirectory.subDirectories.length === 1
+  ) {
+    const onlySubDirectory = currentResultingMergedDirectory.subDirectories[0]!;
+    currentResultingMergedDirectory = {
+      ...onlySubDirectory,
+      directoryName: path.join(
+        currentResultingMergedDirectory.directoryName,
+        onlySubDirectory.directoryName,
+      ),
+    };
+  }
+
+  return currentResultingMergedDirectory;
+};
+
+export const getEmailsDirectoryMetadata = async (
+  absolutePathToEmailsDirectory: string,
+  keepFileExtensions = false,
+  isSubDirectory = false,
+
+  baseDirectoryPath = absolutePathToEmailsDirectory,
+): Promise<EmailsDirectory | undefined> => {
+  if (!fs.existsSync(absolutePathToEmailsDirectory)) return;
+
+  const dirents = await fs.promises.readdir(absolutePathToEmailsDirectory, {
+    withFileTypes: true,
+  });
+
+  const isEmailPredicates = await Promise.all(
+    dirents.map((dirent) =>
+      isFileAnEmail(path.join(absolutePathToEmailsDirectory, dirent.name)),
+    ),
+  );
+  const emailFilenames = dirents
+    .filter((_, i) => isEmailPredicates[i])
+    .map((dirent) =>
+      keepFileExtensions
+        ? dirent.name
+        : dirent.name.replace(path.extname(dirent.name), ''),
+    );
+
+  const subDirectories = await Promise.all(
+    dirents
+      .filter(
+        (dirent) =>
+          dirent.isDirectory() &&
+          !dirent.name.startsWith('_') &&
+          dirent.name !== 'static',
+      )
+      .map((dirent) => {
+        const direntAbsolutePath = path.join(
+          absolutePathToEmailsDirectory,
+          dirent.name,
+        );
+
+        return getEmailsDirectoryMetadata(
+          direntAbsolutePath,
+          keepFileExtensions,
+          true,
+          baseDirectoryPath,
+        ) as Promise<EmailsDirectory>;
+      }),
+  );
+
+  const emailsMetadata = {
+    absolutePath: absolutePathToEmailsDirectory,
+    relativePath: path.relative(
+      baseDirectoryPath,
+      absolutePathToEmailsDirectory,
+    ),
+    directoryName: absolutePathToEmailsDirectory.split(path.sep).pop()!,
+    emailFilenames,
+    subDirectories,
+  } satisfies EmailsDirectory;
+
+  return isSubDirectory
+    ? mergeDirectoriesWithSubDirectories(emailsMetadata)
+    : emailsMetadata;
+};

package/src/utils/get-line-and-column-from-offset.spec.ts

@@ -0,0 +1,11 @@
+import { getLineAndColumnFromOffset } from './get-line-and-column-from-offset';
+
+test('getLineAndColumnFromOffset()', () => {
+  const content = `export default function MyEmail() {
+  return <div className="testing classes to make sure this is not removed" id="my-div" aria-label="my beautiful div">
+    inside the div, should also stay unchanged
+  </div>;
+}`;
+  const offset = content.indexOf('className');
+  expect(getLineAndColumnFromOffset(offset, content)).toEqual([2, 15]);
+});

package/src/utils/get-line-and-column-from-offset.ts

@@ -0,0 +1,11 @@
+export const getLineAndColumnFromOffset = (
+  offset: number,
+  content: string,
+): [line: number, column: number] => {
+  const lineBreaks = [...content.slice(0, offset).matchAll(/\n|\r|\r\n/g)];
+
+  const line = lineBreaks.length + 1;
+  const column = offset - (lineBreaks[lineBreaks.length - 1]?.index ?? 0);
+
+  return [line, column];
+};