react-email 4.0.0-alpha.5 → 4.0.0-alpha.7

package/src/actions/email-validation/check-compatibility.ts

@@ -0,0 +1,321 @@
+'use server';
+import { parse } from '@babel/parser';
+import traverse from '@babel/traverse';
+import {
+  type SourceLocation,
+  convertLocationIntoObject,
+  getObjectVariables,
+} from '../../utils/caniemail/ast/get-object-variables';
+import type { StylePropertyUsage } from '../../utils/caniemail/ast/get-used-style-properties';
+import {
+  doesPropertyHaveLocation,
+  getUsedStyleProperties,
+} from '../../utils/caniemail/ast/get-used-style-properties';
+import type {
+  CompatibilityStats,
+  SupportStatus,
+} from '../../utils/caniemail/get-compatibility-stats-for-entry';
+import { getCompatibilityStatsForEntry } from '../../utils/caniemail/get-compatibility-stats-for-entry';
+import { getCssFunctions } from '../../utils/caniemail/get-css-functions';
+import { getCssPropertyNames } from '../../utils/caniemail/get-css-property-names';
+import { getCssPropertyWithValue } from '../../utils/caniemail/get-css-property-with-value';
+import { getCssUnit } from '../../utils/caniemail/get-css-unit';
+import { getElementAttributes } from '../../utils/caniemail/get-element-attributes';
+import { getElementNames } from '../../utils/caniemail/get-element-names';
+import { supportEntries } from './caniemail-data';
+
+export interface CompatibilityCheckingResult {
+  location: SourceLocation;
+  source: string;
+  entry: SupportEntry;
+  status: SupportStatus;
+  statsPerEmailClient: CompatibilityStats['perEmailClient'];
+}
+
+export type EmailClient =
+  | 'gmail'
+  | 'outlook'
+  | 'yahoo'
+  | 'apple-mail'
+  | 'aol'
+  | 'thunderbird'
+  | 'microsoft'
+  | 'samsung-email'
+  | 'sfr'
+  | 'orange'
+  | 'protonmail'
+  | 'hey'
+  | 'mail-ru'
+  | 'fastmail'
+  | 'laposte'
+  | 't-online-de'
+  | 'free-fr'
+  | 'gmx'
+  | 'web-de'
+  | 'ionos-1and1'
+  | 'rainloop'
+  | 'wp-pl';
+
+export type Platform =
+  | 'desktop-app'
+  | 'desktop-webmail'
+  | 'mobile-webmail'
+  | 'webmail'
+  | 'ios'
+  | 'android'
+  | 'windows'
+  | 'macos'
+  | 'windows-mail'
+  | 'outlook-com';
+
+export type SupportEntryCategroy = 'html' | 'css' | 'image' | 'others';
+
+export interface SupportEntry {
+  slug: string;
+  title: string;
+  description: string | null;
+  url: string;
+  category: SupportEntryCategroy;
+  tags: string[];
+  keywords: string | null;
+  last_test_date: string;
+  test_url: string;
+  test_results_url: string | null;
+  stats: Partial<
+    Record<
+      EmailClient,
+      Partial<
+        Record<
+          Platform,
+          /*
+            This last Record<string, string> has only one key, as the
+            ordered version of caniemail's data is meant to be something like:
+           
+            [
+              { "1.0": "u" },
+              { "2.0": "y" },
+              { "3.0": "p #1" },
+            ]
+           
+            So only one key for each object inside of this array, TypeScript can't really
+            describe this though AFAIK.
+          */
+          Record</* version */ string, string>[]
+        >
+      >
+    >
+  >;
+  notes: string | null;
+  notes_by_num: Record<number, string> | null;
+}
+
+const relevantEmailClients: EmailClient[] = [
+  'gmail',
+  'apple-mail',
+  'outlook',
+  'yahoo',
+];
+
+export const checkCompatibility = async (
+  reactCode: string,
+  emailPath: string,
+) => {
+  const ast = parse(reactCode, {
+    strictMode: false,
+    errorRecovery: true,
+    sourceType: 'unambiguous',
+    plugins: ['jsx', 'typescript', 'decorators'],
+  });
+
+  const getSourceCodeAt = (location: SourceLocation) => {
+    const codeLines = reactCode.split(/\n|\r|\r\n/);
+    const source = codeLines
+      .slice(
+        Math.max(location.start.line - 2, 0),
+        Math.min(location.end.line + 2, codeLines.length),
+      )
+      .join('\n');
+    return source;
+  };
+
+  const objectVariables = getObjectVariables(ast);
+  const usedStyleProperties = await getUsedStyleProperties(
+    ast,
+    reactCode,
+    emailPath,
+    objectVariables,
+  );
+  const readableStream = new ReadableStream<CompatibilityCheckingResult>({
+    async start(controller) {
+      for (const entry of supportEntries) {
+        const compatibilityStats = getCompatibilityStatsForEntry(
+          entry,
+          relevantEmailClients,
+        );
+        if (Object.keys(compatibilityStats.perEmailClient).length === 0)
+          continue;
+        if (compatibilityStats.status === 'success') continue;
+
+        if (entry.category === 'html') {
+          const entryElements = getElementNames(entry.title, entry.keywords);
+          const entryAttributes = getElementAttributes(entry.title);
+          const htmlEntryType = (() => {
+            if (entryElements.length > 0) {
+              return 'element';
+            }
+
+            if (entryAttributes.length > 0) {
+              return 'attribute';
+            }
+          })();
+
+          if (!htmlEntryType) continue;
+
+          let addedInsight = false;
+          if (htmlEntryType === 'element') {
+            traverse(ast, {
+              JSXOpeningElement(path) {
+                if (path.node.name.type === 'JSXIdentifier' && !addedInsight) {
+                  const elementName = path.node.name.name;
+                  if (
+                    entryElements.includes(elementName) &&
+                    path.node.name.loc
+                  ) {
+                    addedInsight = true;
+                    controller.enqueue({
+                      entry,
+                      source: getSourceCodeAt(path.node.name.loc),
+                      location: convertLocationIntoObject(path.node.name.loc),
+                      statsPerEmailClient: compatibilityStats.perEmailClient,
+                      status: compatibilityStats.status,
+                    });
+                  }
+                }
+              },
+            });
+          } else {
+            traverse(ast, {
+              JSXAttribute(path) {
+                if (path.node.name.type === 'JSXIdentifier' && !addedInsight) {
+                  const attributeName = path.node.name.name;
+                  if (
+                    entryAttributes.includes(attributeName) &&
+                    path.node.name.loc
+                  ) {
+                    addedInsight = true;
+                    controller.enqueue({
+                      entry,
+                      source: getSourceCodeAt(path.node.name.loc),
+                      location: convertLocationIntoObject(path.node.name.loc),
+                      statsPerEmailClient: compatibilityStats.perEmailClient,
+                      status: compatibilityStats.status,
+                    });
+                  }
+                }
+              },
+            });
+          }
+        }
+
+        if (entry.category === 'css') {
+          const entryFullProperty = getCssPropertyWithValue(entry.title);
+          const entryProperties = getCssPropertyNames(
+            entry.title,
+            entry.keywords,
+          );
+          const entryUnit = getCssUnit(entry.title);
+          const entryFunctions = getCssFunctions(entry.title);
+
+          const cssEntryType = (() => {
+            if (entryFullProperty?.name && entryFullProperty.value) {
+              return 'full property';
+            }
+
+            if (entryFunctions.length > 0) {
+              return 'function';
+            }
+
+            if (entryUnit) {
+              return 'unit';
+            }
+
+            if (entryProperties.length > 0) {
+              return 'property name';
+            }
+          })();
+
+          if (!cssEntryType) continue;
+          const addToInsights = (
+            property: StylePropertyUsage & { location: SourceLocation },
+          ) => {
+            controller.enqueue({
+              entry,
+              location: convertLocationIntoObject(property.location),
+              source: getSourceCodeAt(property.location),
+              statsPerEmailClient: compatibilityStats.perEmailClient,
+              status: compatibilityStats.status,
+            });
+          };
+
+          for (const property of usedStyleProperties) {
+            if (!doesPropertyHaveLocation(property)) {
+              throw new Error(
+                "One of the properties' node did not contain the proper location for it on the source code. This must be an issue because we always need access to the source.",
+                {
+                  cause: {
+                    property,
+                    entry,
+                    reactCode,
+                    ast,
+                  },
+                },
+              );
+            }
+
+            if (cssEntryType === 'full property') {
+              if (
+                property.name === entryFullProperty?.name &&
+                property.value === entryFullProperty.value
+              ) {
+                addToInsights(property);
+                break;
+              }
+            } else if (cssEntryType === 'function') {
+              const functionRegex =
+                /(?<functionName>[a-zA-Z_][a-zA-Z0-9_-]*)\s*\(/g;
+              const functionName = functionRegex.exec(property.value)?.groups
+                ?.functionName;
+              if (functionName !== undefined) {
+                if (entryFunctions.includes(functionName)) {
+                  addToInsights(property);
+                  break;
+                }
+              }
+            } else if (cssEntryType === 'unit') {
+              const match = property.value.match(/[0-9](?<unit>[a-zA-Z%]+)$/g);
+              if (match) {
+                const unit = match.groups?.unit;
+                if (entryUnit && unit && entryUnit === unit) {
+                  addToInsights(property);
+                  break;
+                }
+              }
+            } else if (
+              entryProperties.some(
+                (propertyName) => property.name === propertyName,
+              )
+            ) {
+              addToInsights(property);
+              break;
+            }
+          }
+        }
+      }
+      controller.close();
+    },
+  });
+
+  return readableStream;
+};
+
+export type AST = ReturnType<typeof parse>;

package/src/actions/email-validation/check-images.spec.tsx

@@ -1,18 +1,12 @@
-import { render } from '@react-email/render';
 import { type ImageCheckingResult, checkImages } from './check-images';
 
 test('checkImages()', async () => {
   const results: ImageCheckingResult[] = [];
-  const stream = await checkImages(
-    await render(
-      <div>
-        {/* biome-ignore lint/a11y/useAltText: This is intentional to test the checking for accessibility */}
-        <img src="https://resend.com/static/brand/resend-icon-white.png" />,
-        <img src="/static/codepen-challengers.png" alt="codepen challenges" />,
-      </div>,
-    ),
-    'https://demo.react.email',
-  );
+  const html = `<div>
+  <img src="https://resend.com/static/brand/resend-icon-white.png" />,
+  <img src="/static/codepen-challengers.png" alt="codepen challenges" />,
+</div>`;
+  const stream = await checkImages(html, 'https://demo.react.email');
   const reader = stream.getReader();
   while (true) {
     const { done, value } = await reader.read();
@@ -25,7 +19,11 @@ test('checkImages()', async () => {
   }
   expect(results).toEqual([
     {
-      intendedFor: 'https://resend.com/static/brand/resend-icon-white.png',
+      source: 'https://resend.com/static/brand/resend-icon-white.png',
+      codeLocation: {
+        line: 2,
+        column: 3,
+      },
       checks: [
         {
           passed: false,
@@ -60,6 +58,10 @@ test('checkImages()', async () => {
       status: 'warning',
     },
     {
+      codeLocation: {
+        line: 3,
+        column: 3,
+      },
       checks: [
         {
           metadata: {
@@ -91,7 +93,7 @@ test('checkImages()', async () => {
           type: 'image_size',
         },
       ],
-      intendedFor: '/static/codepen-challengers.png',
+      source: '/static/codepen-challengers.png',
       status: 'success',
     },
   ] satisfies ImageCheckingResult[]);

package/src/actions/email-validation/check-images.ts

@@ -2,6 +2,10 @@
 
 import type { IncomingMessage } from 'node:http';
 import { parse } from 'node-html-parser';
+import {
+  type CodeLocation,
+  getCodeLocationFromAstElement,
+} from './get-code-location-from-ast-element';
 import { quickFetch } from './quick-fetch';
 
 export type ImageCheck = { passed: boolean } & (
@@ -33,7 +37,8 @@ export type ImageCheck = { passed: boolean } & (
 
 export interface ImageCheckingResult {
   status: 'success' | 'warning' | 'error';
-  intendedFor: string;
+  source: string;
+  codeLocation: CodeLocation;
   checks: ImageCheck[];
 }
 
@@ -60,7 +65,8 @@ export const checkImages = async (code: string, base: string) => {
           : rawSource;
 
         const result: ImageCheckingResult = {
-          intendedFor: rawSource,
+          source: rawSource,
+          codeLocation: getCodeLocationFromAstElement(image, code),
           status: 'success',
           checks: [],
         };

package/src/actions/email-validation/check-links.spec.tsx

@@ -1,18 +1,14 @@
-import { render } from '@react-email/render';
 import { type LinkCheckingResult, checkLinks } from './check-links';
 
 test('checkLinks()', async () => {
   const results: LinkCheckingResult[] = [];
-  const stream = await checkLinks(
-    await render(
-      <div>
-        <a href="/">Root</a>
-        <a href="https://resend.com">Resend</a>
-        <a href="https://notion.so">Notion</a>
-        <a href="http://react.email">React Email unsafe</a>
-      </div>,
-    ),
-  );
+  const html = `<div>
+  <a href="/">Root</a>
+  <a href="https://resend.com">Resend</a>
+  <a href="https://notion.so">Notion</a>
+  <a href="http://react.email">React Email unsafe</a>
+</div>`;
+  const stream = await checkLinks(html);
   const reader = stream.getReader();
   while (true) {
     const { done, value } = await reader.read();
@@ -26,16 +22,24 @@ test('checkLinks()', async () => {
   expect(results).toEqual([
     {
       status: 'error',
+      codeLocation: {
+        line: 2,
+        column: 3,
+      },
       checks: [
         {
           type: 'syntax',
           passed: false,
         },
       ],
-      intendedFor: '/',
+      link: '/',
     },
     {
       status: 'success',
+      codeLocation: {
+        line: 3,
+        column: 3,
+      },
       checks: [
         {
           type: 'syntax',
@@ -53,10 +57,14 @@ test('checkLinks()', async () => {
           },
         },
       ],
-      intendedFor: 'https://resend.com',
+      link: 'https://resend.com',
     },
     {
       status: 'warning',
+      codeLocation: {
+        line: 4,
+        column: 3,
+      },
       checks: [
         {
           type: 'syntax',
@@ -74,10 +82,14 @@ test('checkLinks()', async () => {
           passed: false,
         },
       ],
-      intendedFor: 'https://notion.so',
+      link: 'https://notion.so',
     },
     {
       status: 'warning',
+      codeLocation: {
+        line: 5,
+        column: 3,
+      },
       checks: [
         {
           type: 'syntax',
@@ -95,7 +107,7 @@ test('checkLinks()', async () => {
           passed: false,
         },
       ],
-      intendedFor: 'http://react.email',
+      link: 'http://react.email',
     },
   ] satisfies LinkCheckingResult[]);
 });

package/src/actions/email-validation/check-links.ts

@@ -1,6 +1,10 @@
 'use server';
 
 import { parse } from 'node-html-parser';
+import {
+  type CodeLocation,
+  getCodeLocationFromAstElement,
+} from './get-code-location-from-ast-element';
 import { quickFetch } from './quick-fetch';
 
 export type LinkCheck = { passed: boolean } & (
@@ -20,7 +24,8 @@ export type LinkCheck = { passed: boolean } & (
 
 export interface LinkCheckingResult {
   status: 'success' | 'warning' | 'error';
-  intendedFor: string;
+  link: string;
+  codeLocation: CodeLocation;
   checks: LinkCheck[];
 }
 
@@ -36,7 +41,8 @@ export const checkLinks = async (code: string) => {
         if (link.startsWith('mailto:')) continue;
 
         const result: LinkCheckingResult = {
-          intendedFor: link,
+          link,
+          codeLocation: getCodeLocationFromAstElement(anchor, code),
           status: 'success',
           checks: [],
         };

package/src/actions/email-validation/get-code-location-from-ast-element.ts

@@ -0,0 +1,18 @@
+import type { HTMLElement } from 'node-html-parser';
+import { getLineAndColumnFromOffset } from '../../utils/get-line-and-column-from-offset';
+
+export interface CodeLocation {
+  line: number;
+  column: number;
+}
+
+export const getCodeLocationFromAstElement = (
+  ast: HTMLElement,
+  html: string,
+): CodeLocation => {
+  const [line, column] = getLineAndColumnFromOffset(ast.range[0], html);
+  return {
+    line,
+    column,
+  };
+};

package/src/actions/get-email-path-from-slug.ts

@@ -2,7 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { cache } from 'react';
-import { emailsDirectoryAbsolutePath } from '../utils/emails-directory-absolute-path';
+import { emailsDirectoryAbsolutePath } from '../app/env';
 
 // eslint-disable-next-line @typescript-eslint/require-await
 export const getEmailPathFromSlug = cache(async (slug: string) => {

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

@@ -4,6 +4,7 @@ import path from 'node:path';
 import chalk from 'chalk';
 import logSymbols from 'log-symbols';
 import ora from 'ora';
+import { isBuilding, isPreviewDevelopment } from '../app/env';
 import { getEmailComponent } from '../utils/get-email-component';
 import { improveErrorWithSourceMap } from '../utils/improve-error-with-sourcemap';
 import { registerSpinnerAutostopping } from '../utils/register-spinner-autostopping';
@@ -35,7 +36,7 @@ export const renderEmailByPath = async (
 
   const emailFilename = path.basename(emailPath);
   let spinner: ora.Ora | undefined;
-  if (process.env.NEXT_PUBLIC_IS_BUILDING !== 'true') {
+  if (!isBuilding && !isPreviewDevelopment) {
     spinner = ora({
       text: `Rendering email template ${emailFilename}\n`,
       prefixText: ' ',

package/src/{utils/emails-directory-absolute-path.ts → app/env.ts}

@@ -8,3 +8,8 @@ export const userProjectLocation = process.env.USER_PROJECT_LOCATION!;
 /** ONLY ACCESSIBLE ON THE SERVER */
 export const emailsDirectoryAbsolutePath =
   process.env.EMAILS_DIR_ABSOLUTE_PATH!;
+
+export const isBuilding = process.env.NEXT_PUBLIC_IS_BUILDING === 'true';
+
+export const isPreviewDevelopment =
+  process.env.NEXT_PUBLIC_IS_PREVIEW_DEVELOPMENT === 'true';

package/src/app/layout.tsx

@@ -1,8 +1,8 @@
 import type { Metadata } from 'next';
 import './globals.css';
 import { EmailsProvider } from '../contexts/emails';
-import { emailsDirectoryAbsolutePath } from '../utils/emails-directory-absolute-path';
 import { getEmailsDirectoryMetadata } from '../utils/get-emails-directory-metadata';
+import { emailsDirectoryAbsolutePath } from './env';
 import { inter, sfMono } from './fonts';
 
 export const metadata: Metadata = {

package/src/app/page.tsx

@@ -4,7 +4,7 @@ import Link from 'next/link';
 import { Button, Heading, Text } from '../components';
 import CodeSnippet from '../components/code-snippet';
 import { Shell, ShellContent } from '../components/shell';
-import { emailsDirectoryAbsolutePath } from '../utils/emails-directory-absolute-path';
+import { emailsDirectoryAbsolutePath } from './env';
 import logo from './logo.png';
 
 const Home = () => {