feat(react-email): added configuration handling for react-email and preview server

[Shubhdeep12]

• to introduce a config file react-email.config.(mjs/cjs/js/json) as the unified configuration source for the CLI and preview server in a repository.
• added email init command to generate the config.
• added fixtures and tests
  related To have a unified config for react-email #2985

---

Summary by cubic

Adds a unified react-email.config.* for the CLI and preview server, plus a new init command to scaffold it. CLI commands now use config defaults for emailsDir and port, with flags as overrides.

• New Features

  • Support react-email.config.{mjs,cjs,js,json} with emailsDir and preview.{port, emailsDir}; added npx react-email init to scaffold it.
  • dev, build, and export read config by default; flags override; dev logs when using defaults without a config; safer port parsing; preview UI env reads moved to env.client; tests and docs added.
  • Email directory resolution order: env var > preview.emailsDir > emailsDir > ./emails.

• Migration

  • Optional: run npx react-email init to create a config at the project root.
  • If running the preview server standalone, set emailsDir via the config or REACT_EMAIL_INTERNAL_EMAILS_DIR_ABSOLUTE_PATH; otherwise it falls back to ./emails.

^{Written for commit 0e97d76. Summary will update on new commits.}

[vercel]

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

A member of the Team first needs to authorize it.

[changeset-bot]

🦋 Changeset detected

Latest commit: 0e97d76

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

[cubic-dev-ai]

6 issues found across 21 files

Confidence score: 3/5

• There is a concrete regression risk in packages/react-email/src/index.ts: exporting defineConfig from a side-effectful CLI entrypoint can trigger startup/arg parsing during import, which can break expected library-style usage.
• Several medium-severity, high-confidence issues affect runtime robustness (packages/react-email/src/commands/dev.ts, packages/react-email/src/commands/build.ts, packages/react-email/src/commands/init.ts), including unvalidated port values, path handling mismatches, and --force behavior that may not actually override active JS/MJS/CJS configs.
• Given the concentration of 5-7/10 issues with high confidence and user-facing failure modes, this looks mergeable only with some caution rather than low-risk.
• Pay close attention to packages/react-email/src/index.ts, packages/react-email/src/commands/dev.ts, packages/react-email/src/commands/build.ts, packages/react-email/src/commands/init.ts, packages/react-email/src/utils/load-config.ts, packages/preview-server/src/utils/load-preview-config.ts - side effects and missing runtime validation can propagate malformed config into startup/build failures.

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/utils/load-config.ts">

<violation number="1" location="packages/react-email/src/utils/load-config.ts:32">
P2: Runtime config is type-cast without validation, allowing malformed user config values to propagate and break downstream path/port handling.</violation>
</file>

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

<violation number="1" location="packages/react-email/src/commands/dev.ts:16">
P2: Port parsing from CLI/config lacks validation, allowing malformed values to reach server startup.</violation>
</file>

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

<violation number="1" location="packages/react-email/src/commands/init.ts:41">
P2: `init --force` claims to overwrite existing config files but only writes `react-email.config.json`, leaving higher-priority JS/MJS/CJS configs active.</violation>
</file>

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

<violation number="1" location="packages/react-email/src/commands/build.ts:181">
P2: `emailsDir` from CLI/config is not constrained to relative paths, but later logic treats it as relative, causing directory mismatch and possible build failures.</violation>
</file>

<file name="packages/preview-server/src/utils/load-preview-config.ts">

<violation number="1" location="packages/preview-server/src/utils/load-preview-config.ts:30">
P2: User-authored config is cast with TypeScript assertions only, so invalid runtime shapes can propagate and cause runtime failures when consumed.</violation>
</file>

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

<violation number="1" location="packages/react-email/src/index.ts:17">
P1: `defineConfig` is exported from a side-effectful CLI entrypoint, so importing it can execute CLI startup/parse logic instead of acting like a pure utility import.</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/resend/react-email/@react-email/preview-server@2984

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

commit: 0e97d76

[cubic-dev-ai]

6 issues found across 12 files (changes from recent commits).

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/utils/load-config.ts">

<violation number="1" location="packages/react-email/src/utils/load-config.ts:60">
P2: JSON config read/parse errors are swallowed, causing broken config files to fail silently without warning.</violation>
</file>

<file name="packages/preview-server/src/utils/load-preview-config.ts">

<violation number="1" location="packages/preview-server/src/utils/load-preview-config.ts:58">
P2: JSON config read/parse errors are swallowed, so malformed config files fail silently without the warning in loadReactEmailConfig.</violation>
</file>

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

<violation number="1" location="packages/react-email/src/commands/dev.ts:18">
P2: Port parsing now rejects 0 and silently falls back to 3000, preventing use of ephemeral ports (server.listen(0)) and changing behavior for users/configs that set port 0.</violation>
</file>

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

<violation number="1" location="packages/react-email/src/commands/build.ts:30">
P2: Windows cross-drive absolute paths bypass the outside-project check, causing malformed `path.join` results and incorrect directory resolution.</violation>

<violation number="2" location="packages/react-email/src/commands/build.ts:30">
P2: Build silently rewrites absolute external emailsDir to `./emails`, overriding user intent and potentially building the wrong templates.</violation>
</file>

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

<violation number="1" location="packages/react-email/src/index.ts:25">
P1: Entrypoint detection uses brittle path equality and can fail for symlink/bin shim invocation, causing the CLI startup path to be skipped entirely.</violation>
</file>

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