email export fails with JavaScript heap OOM when exporting a large number of templates

[framebassman]

What versions are you using? (if relevant)

react-email@5.x

Describe the Bug

When exporting a large number of email templates using react-email, the email export command may fail with a JavaScript heap out-of-memory (OOM) error.

In projects with a high number of email templates (≈670 React components), react-email loads all templates at once and passes them as entry points to a single esbuild.build() call. This causes Node.js memory usage to exceed the default heap limit (~4GB), leading to a fatal OOM crash.

Currently, there is no way to configure or forward Node.js heap size options (e.g. --max-old-space-size) to the esbuild process from the react-email CLI.

Environment
OS: Linux
Node.js: Snap-installed Node (OOM occurs around ~4GB heap)
Package manager: pnpm
react-email version: 1.1.0
Command used: npx email export

What is affected (leave empty if unsure)

CLI

Link to the code that reproduces this issue

https://github.com/framebassman/react-email-oom-issue

To Reproduce

Steps to Reproduce

• Create a project using react-email
• Add a large number of email templates (≈600–700 React components)
• Run: npx email export
• Observe the process during the rendering/build step

Actual Behavior
The process crashes with a fatal JavaScript heap out-of-memory error:

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

GC logs indicate memory usage reaching ~4GB before failure.

Expected Behavior

Expected Behavior

• Emails should be exported successfully, even for large template counts
• OR the tool should provide a way to:
  • Limit concurrency
  • Batch builds
  • Configure Node.js heap size
  • Or fail gracefully with a clear error message and workaround

What's your node version? (if relevant)

No response

[framebassman]

Technical Analysis

react-email gathers all templates and passes them as entry points to a single esbuild.build() call:

const allTemplates = getEmailTemplatesFromDirectory(emailsDirectoryMetadata);

await build({
  bundle: true,
  entryPoints: allTemplates,
  format: 'cjs',
  jsx: 'automatic',
  loader: { '.js': 'jsx' },
  logLevel: 'silent',
  outExtension: { '.js': '.cjs' },
  outdir: pathToWhereEmailMarkupShouldBeDumped,
  platform: 'node',
  plugins: [renderingUtilitiesExporter(allTemplates)],
  write: true,
});

Source:

react-email/packages/react-email/src/commands/export.ts

Line 77 in 60e3a7f

const allTemplates = getEmailTemplatesFromDirectory(emailsDirectoryMetadata);

This approach:

• Loads all templates into memory simultaneously
• Prevents batching or streaming
• Does not expose any configuration for Node.js memory limits
• Makes it impossible to pass NODE_OPTIONS=--max-old-space-size=... via the CLI

Impact

• react-email becomes unusable for large-scale email libraries
• Blocks adoption in enterprise or multi-tenant systems
• Forces users to manually split projects or maintain multiple exports

Suggested Improvements

1. Batch export templates instead of building all at once
2. Maybe add a CLI option for:

• --batch-size
• --max-heap

Workarounds (Current)

• Manually split templates into smaller directories
• Maintain multiple export runs

[framebassman]

Ok, so seems the root cause is not in the esbuild command, but in the render method of emailModule:

await emailModule.render(
  emailModule.reactEmailCreateReactElement(emailModule.default, {}),
  options,
);

react-email/packages/react-email/src/commands/export.ts

Line 133 in 60e3a7f

const rendered = await emailModule.render(

[pthneo]

Would love to see a fix for this, getting OOM issues constantly.