feat(preview-server): bundle to esm 💫

[gabrielmfern]

I hate CJS, and we needed top-level await for better integrations, so the stars have aligned for this.

To actually make this happen, we're just switching esbuild's options from format: 'cjs' to format: 'esm' and now using vm's Module support through the --experimental-vm-modules. The main bit of documentation for what we're using here can be found in https://nodejs.org/api/vm.html#class-vmsourcetextmodule

---

Summary by cubic

Switch preview-server bundling from CommonJS to ESM to enable top‑level await and modern import semantics. Uses Node’s vm SourceTextModule with experimental VM modules and updates scripts to set NODE_OPTIONS.

• New Features

  • Build bundled templates and Tailwind config as ESM (esbuild format: 'esm').
  • Async runBundledCode executes ESM in a VM via SourceTextModule; supports dynamic imports, import.meta (with meta.resolve), node: built-ins via SyntheticModule, and CJS default-export interop.
  • Updated callers to await runBundledCode in get-email-component and Tailwind config; improved error handling for unknown errors.
  • Added a unit test for VM execution.
  • preview-server scripts set NODE_OPTIONS=--experimental-vm-modules --disable-warning=ExperimentalWarning for build/dev/test/test:watch.
  • react-email dev and CLI run with --experimental-vm-modules, suppress the ExperimentalWarning, and preserve existing NODE_OPTIONS.

• Migration

  • No action if using provided scripts or the react-email CLI. If running custom commands, include NODE_OPTIONS=--experimental-vm-modules --disable-warning=ExperimentalWarning.

^{Written for commit 7c00644. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 7c00644

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@react-email/preview-server	Minor
react-email	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
react-email	Ready	Preview, Comment	Dec 30, 2025 5:56pm
react-email-demo	Ready	Preview, Comment	Dec 30, 2025 5:56pm

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/resend/react-email/@react-email/preview-server@2733

npm i https://pkg.pr.new/resend/react-email@2733

commit: 7c00644

[cubic-dev-ai]

4 issues found across 7 files

Prompt for AI agents (all 4 issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/preview-server/src/utils/run-bundled-code.spec.ts">

<violation number="1" location="packages/preview-server/src/utils/run-bundled-code.spec.ts:6">
P2: Rule violated: **No `should` in tests**

Test description uses &#39;should&#39;. Use declarative language instead: &#39;runs the bundled code in a VM context&#39;.</violation>

<violation number="2" location="packages/preview-server/src/utils/run-bundled-code.spec.ts:21">
P2: Rule violated: **No `should` in tests**

Test description uses &#39;should&#39;. Use declarative language instead: &#39;returns an error if the code throws&#39;.</violation>
</file>

<file name="packages/preview-server/src/utils/get-email-component.ts">

<violation number="1" location="packages/preview-server/src/utils/get-email-component.ts:86">
P1: The `context` object is spread/copied into the VM context during `runBundledCode`. Later modifications to `context.shouldIncludeSourceReference` in `renderWithReferences` won&#39;t be visible inside the VM, breaking the source reference feature. Consider either returning the contextified object from `runBundledCode` so it can be modified directly, or using a different mechanism to communicate with the VM at render time.</violation>
</file>

<file name="packages/preview-server/src/utils/run-bundled-code.ts">

<violation number="1" location="packages/preview-server/src/utils/run-bundled-code.ts:37">
P2: `import.meta.resolve` is module-scoped and will resolve relative specifiers from `run-bundled-code.ts` rather than from `filename`. Consider wrapping it to use the correct parent URL.</violation>
</file>

_{Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR}

[socket-security]

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

View full report

[cubic-dev-ai]

2 issues found across 9 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/react-email/dev/index.js">

<violation number="1" location="packages/react-email/dev/index.js:16">
P2: Setting `NODE_OPTIONS` overwrites any existing value from the user&#39;s environment. Consider appending to preserve user-defined Node options.</violation>
</file>

<file name="packages/react-email/src/index.ts">

<violation number="1" location="packages/react-email/src/index.ts:1">
P1: This shebang won&#39;t work correctly on most Unix systems. Without the `-S` flag, `env` treats everything after the program name as a single argument. Use `#!/usr/bin/env -S node --experimental-vm-modules --disable-warning=ExperimentalWarning` to properly split the arguments. The `-S` flag is supported by GNU coreutils 8.30+ (2018) and most modern BSD/macOS systems.</violation>
</file>

_{Reply to cubic to teach it or ask questions. Tag @cubic-dev-ai to re-run a review.}