feat(react-email): add email config support

[itsyoboieltr]

Summary by cubic

Adds optional email config support to react-email, letting projects define email.config.* to inject custom esbuild plugins in exports and the preview UI. Ships react-email/config with typed helpers and config validation. No breaking changes.

• New Features

  • Detects email.config.ts|mts|cts|js|mjs|cjs via getEmailConfigPath, and loads configs with getEmailConfig using jiti.
  • Adds react-email/config subpath export with defineConfig, getEmailConfig, and getEmailConfigPath.
  • Passes REACT_EMAIL_INTERNAL_EMAIL_CONFIG_PATH to preview/build, and applies config esbuild plugins in exportTemplates and UI getEmailComponent.

• Bug Fixes

  • Fixed quoting of the config path env var.
  • getEmailConfigPath returns undefined when no config is found.
  • Validates config shape and esbuild.plugins array with helpful errors.
  • Externalized and added jiti in preview/build and the UI to ensure runtime config loading.

^{Written for commit 7babd59. Summary will update on new commits. Review in cubic}

[changeset-bot]

🦋 Changeset detected

Latest commit: 7babd59

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

This PR includes changesets to release 3 packages

Name	Type
react-email	Minor
@react-email/ui	Minor
@react-email/editor	Patch

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]

@itsyoboieltr is attempting to deploy a commit to the resend Team on Vercel.

A member of the Team first needs to authorize it.

[cubic-dev-ai]

2 issues found across 20 files

Confidence score: 3/5

• There is a concrete regression risk in packages/react-email/src/cli/commands/build.ts: interpolating emailConfigPath into a single-quoted template without escaping can generate invalid next.config.mjs and break builds for paths containing '.
• packages/react-email/src/config/get-email-config.ts has moderate validation looseness (arrays accepted as top-level config), which can let invalid exports pass silently and surface errors later.
• Given a high-confidence medium-severity build-time issue plus another config-validation gap, this carries some user-facing risk and is worth fixing before merge if possible.
• Pay close attention to packages/react-email/src/cli/commands/build.ts and packages/react-email/src/config/get-email-config.ts - quoting/escaping in generated config and strict top-level config shape validation need verification.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


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

<violation number="1" location="packages/react-email/src/config/get-email-config.ts:22">
P2: Top-level config validation accepts arrays, so invalid config exports can pass silently.</violation>
</file>

<file name="packages/react-email/src/cli/commands/build.ts">

<violation number="1" location="packages/react-email/src/cli/commands/build.ts:39">
P2: Generated `next.config.mjs` can become invalid JavaScript because `emailConfigPath` is injected into a single-quoted string without escaping single quotes.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[pkg-pr-new]

Open in StackBlitz

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

npm i https://pkg.pr.new/@react-email/ui@3411

commit: 7babd59

[gabrielmfern]

I don't think this test is quite useful, as the code is quite simple and just reading it makes it clear if it's right or not. The only effect that this has is making it harder to change the code.

[itsyoboieltr]

removed the test as per your feedback

[gabrielmfern]

What kind of use case does this fix? Do we have any discussion about this already?

I'd rather avoid we add a config file, and imo we should think of other options first. The ecosystem already has lots of config files, and they make projects messier and messier.

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

_{Requires human review: This PR introduces a new configuration system and modifies the core build/preview pipeline across multiple packages, which requires human architectural review.}

[cubic-dev-ai]

0 issues found across 3 files (changes from recent commits).

_{Requires human review: This PR introduces a significant new feature (external configuration support) that modifies core build, export, and preview logic. Such architectural changes require human review.}

[itsyoboieltr]

@gabrielmfern Hey, thanks for checking out my PR.

There is some prior discussion here: #2334. I opened it almost a year ago, and some people expressed interest in the feature.

My main use case is enabling user-provided custom esbuild plugins so email templates can use build-time macros and other compile-time transforms. In my case, that’s for lingui, but the same mechanism would also cover things like custom file loaders, macro transpilation, or loading env values during build.

I understand the concern about adding another config file. I wouldn’t suggest it if there were a simpler workaround, but for build-time changes to email source there doesn’t seem to be a flexible alternative today (other than forking react-email to add plugin support).

If there’s a better way to support this without a config file, I’m open to implementing it as well.