feat(charlie): align next/v3 CLI --use-preview-props behavior with main (#358)

Co-authored-by: CharlieHelps <[email protected]>

Author: charliecreates[bot]

apps/web/src/content/docs/core/cli.mdx

@@ -63,6 +63,8 @@ email build ./emails/Welcome.tsx
 To view info, flags, and options for the `build` command, run `email help build`.
 :::
 
+To render using the sample props you export from a template file, pass the `--use-preview-props` flag. When set, `email build` will use the `previewProps` export (if present) instead of `--props`.
+
 ### Check Command
 
 Verify email client compatibility using [caniuse.com](https://caniemail.com/) data:
@@ -88,6 +90,8 @@ Check Complete: 14 error(s), 20 warning(s)
 To view info, flags, and options for the `check` command, run `email help check`.
 :::
 
+You can also pass `--use-preview-props` so `email check` builds templates using their exported `previewProps`, keeping compatibility checks aligned with the data used for previews and builds.
+
 ### Preview Command
 
 Launch a development server to preview your email templates with these features:

docs/components/graph.md

@@ -18,7 +18,7 @@ This component is wrapper around [QuickChart API](https://quickchart.io/) for ge
 Add the graph component to your email template.
 
 ```jsx
-import { Html, Body, Section, Graph } from 'jsx-email';
+import { Body, Graph, Html, Section } from 'jsx-email';
 
 const Email = () => {
   return (

docs/core/cli.md

@@ -67,6 +67,8 @@ $ cd ~/code/email-app
 $ email build ./emails/Batman.tsx
 ```
 
+To render using the sample props you export from a template file, pass the `--use-preview-props` flag. When set, `email build` will use the `previewProps` export (if present) instead of `--props`.
+
 ## Check
 
 ::: tip
@@ -79,6 +81,8 @@ To view info, flags, and options for the `check` command, run `email help check`
 $ email check ./emails/Batman.tsx
 ```
 
+To check templates using their exported `previewProps`, pass the `--use-preview-props` flag so the check runs against the same sample data as your previews and builds.
+
 Example output:
 
 ```console

docs/core/compile.md

@@ -28,10 +28,10 @@ const compiledFiles = await compile({ files: [templatePath], hashFiles: false, o
 Once compiled into a bundle, the file can be imported and passed to render such like:
 
 ```jsx
-import { Template } from './.compiled/batman.js';
-
 import { render } from 'jsx-email';
 
+import { Template } from './.compiled/batman.js';
+
 const html = render(<Template />);
 ```
 

docs/core/plugins.md

@@ -33,6 +33,7 @@ To instruct a render to use plugins, utilize a [Configuration File](/docs/core/c
 
 ```js
 import { defineConfig } from 'jsx-email/config';
+
 import { somePlugin } from './plugins/some-plugin';
 
 export const config = defineConfig({

packages/jsx-email/src/cli/commands/build.ts

@@ -83,6 +83,8 @@ Builds a template and saves the result
   --props       A JSON string containing props to be passed to the email template
                 This is usually only useful when building a single template, unless all of your
                 templates share the same props.
+  --use-preview-props
+                When set, use the \`previewProps\` exported by the template file (if present).
 
 {underline Examples}
   $ email build ./src/emails

packages/jsx-email/src/cli/commands/check.ts

@@ -4,7 +4,7 @@ import { type IssueGroup, caniemail, groupIssues, sortIssues } from 'caniemail';
 import chalk from 'chalk';
 import chalkTmpl from 'chalk-template';
 import stripAnsi from 'strip-ansi';
-import { type InferOutput as Infer, parse as assert, object } from 'valibot';
+import { type InferOutput as Infer, parse as assert, boolean, object, optional } from 'valibot';
 
 import { formatBytes, gmailByteLimit, gmailBytesSafe } from '../helpers.js';
 
@@ -13,7 +13,9 @@ import { type CommandFn } from './types.js';
 
 const { error, log } = console;
 
-const CheckOptionsStruct = object({});
+const CheckOptionsStruct = object({
+  usePreviewProps: optional(boolean())
+});
 
 type CheckOptions = Infer<typeof CheckOptionsStruct>;
 
@@ -34,6 +36,10 @@ Check jsx-email templates for client compatibility
 {underline Usage}
   $ email check <template file name>
 
+{underline Options}
+  --use-preview-props
+                When set, use the \`previewProps\` exported by the template file (if present).
+
 {underline Examples}
   $ email check ./emails/Batman.tsx
 `;
@@ -129,7 +135,11 @@ export const command: CommandFn = async (argv: CheckOptions, input) => {
   log(chalkTmpl`{blue Checking email template for Client Compatibility...}\n`);
 
   const [file] = await buildTemplates({
-    buildOptions: { showStats: false, writeToFile: false },
+    buildOptions: {
+      showStats: false,
+      writeToFile: false,
+      usePreviewProps: argv.usePreviewProps
+    },
     targetPath: input[0]
   });
 

packages/jsx-email/test/cli/build-use-preview-props.test.ts

@@ -0,0 +1,65 @@
+import { rm } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+import { buildTemplates } from '../../src/cli/commands/build.js';
+
+import { previewProps } from './fixtures/cli-preview-props-template.js';
+
+const templatePath = resolve(__dirname, 'fixtures/cli-preview-props-template.tsx');
+const outDir = resolve(__dirname, '.test-build-preview-props');
+
+describe('cli build --use-preview-props', () => {
+  it('uses template.previewProps when flag is set', async () => {
+    (globalThis as any).__jsxEmailCliPreviewProps = undefined;
+    await rm(outDir, { recursive: true, force: true });
+
+    const [result] = await buildTemplates({
+      buildOptions: {
+        html: true,
+        out: outDir,
+        plain: false,
+        props: JSON.stringify({ source: 'cli', test: 'robin' }),
+        showStats: false,
+        silent: true,
+        usePreviewProps: true,
+        writeToFile: false
+      },
+      targetPath: templatePath
+    });
+
+    const usedProps = (globalThis as any).__jsxEmailCliPreviewProps;
+
+    expect(usedProps).toEqual(previewProps);
+    expect(result.html).toContain('batman');
+    expect(result.html).not.toContain('robin');
+  });
+
+  it('uses --props JSON when usePreviewProps is not set', async () => {
+    (globalThis as any).__jsxEmailCliPreviewProps = undefined;
+    await rm(outDir, { recursive: true, force: true });
+
+    const props = { source: 'cli', test: 'robin' } as const;
+
+    const [result] = await buildTemplates({
+      buildOptions: {
+        html: true,
+        out: outDir,
+        plain: false,
+        props: JSON.stringify(props),
+        showStats: false,
+        silent: true,
+        // `usePreviewProps` intentionally omitted
+        writeToFile: false
+      },
+      targetPath: templatePath
+    });
+
+    const usedProps = (globalThis as any).__jsxEmailCliPreviewProps;
+
+    expect(usedProps).toEqual(props);
+    expect(result.html).toContain('robin');
+    expect(result.html).not.toContain('batman');
+  });
+});

packages/jsx-email/test/cli/check-use-preview-props.test.ts

@@ -0,0 +1,38 @@
+import { resolve } from 'node:path';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { previewProps } from './fixtures/cli-preview-props-template.js';
+
+const caniemailMock = vi.fn(() => ({
+  issues: { errors: new Map(), warnings: undefined },
+  success: true
+}));
+
+vi.mock('caniemail', () => ({
+  caniemail: caniemailMock,
+  groupIssues: () => [],
+  sortIssues: (groups: unknown[]) => groups
+}));
+
+const templatePath = resolve(__dirname, 'fixtures/cli-preview-props-template.tsx');
+
+describe('cli check --use-preview-props', () => {
+  it('builds using template.previewProps when flag is set', async () => {
+    (globalThis as any).__jsxEmailCliPreviewProps = undefined;
+    caniemailMock.mockClear();
+
+    const { command } = await import('../../src/cli/commands/check.js');
+
+    const result = await command({ usePreviewProps: true } as any, [templatePath]);
+
+    expect(result).toBe(true);
+
+    const usedProps = (globalThis as any).__jsxEmailCliPreviewProps;
+    expect(usedProps).toEqual(previewProps);
+
+    expect(caniemailMock).toHaveBeenCalledTimes(1);
+    const [{ html }] = caniemailMock.mock.calls[0] as [{ html: string }];
+    expect(html).toContain('batman');
+  });
+});

packages/jsx-email/test/cli/fixtures/cli-preview-props-template.tsx

@@ -0,0 +1,20 @@
+import { Body, Html } from '../../../src/index.js';
+
+export const previewProps = { source: 'preview', test: 'batman' } as const;
+
+interface TemplateProps {
+  source?: string;
+  test?: string;
+}
+
+export const Template = (props: TemplateProps) => {
+  (globalThis as any).__jsxEmailCliPreviewProps = props;
+
+  return (
+    <Html>
+      <Body>{props.test}</Body>
+    </Html>
+  );
+};
+
+export const templateName = 'cli-preview-props';