Mismatching esbuild versions breaks the preview server

[crudh]

What versions are you using? (if relevant)

@react-email/components@1.0.7, react-email@5.2.8, @react-email/preview-server@5.2.8

Describe the Bug

If there is a dependency in the app, or as in our case any app in a monorepo, to a version of esbuild that doesn't match the one in @react-email/preview-server the preview of the email will crash.

The only way to get it to work if you have a dependency on esbuild in your app is to make sure it matches the version @react-email/preview-server uses. And if in a monorepo you need to make sure all other apps use the same version too.

I think it started happening after this PR which upgraded next and touched the esbuild dep.

Browser:

Terminal:

What is affected (leave empty if unsure)

Preview Server

Link to the code that reproduces this issue

https://github.com/crudh/react-email-esbuild-issue

To Reproduce

• Start the preview using pnpm dev
• Verify that it crashes when trying to preview the email
• Remove the esbuild dev dependency in the app and try again, the preview works

Expected Behavior

I expect not to have to match the version of esbuild in my app/monorepo to the internal one in @react-email/prevew-server to avoid breaking email preview.

What's your node version? (if relevant)

24.13.0

[TiboC]

I reproduce the same issue as the one described by @crudh

"@react-email/components": "^1.0.7"
"@react-email/render": "^2.0.4"
"@react-email/preview-server": "^5.2.8"

[ayinde-xyz]

Install the host version of esbuild

[karlismelderis-mckinsey]

As Next is not shipped with turbopack wouldn't it make sense to replace esbuild with turbopack instead of fixing this case?

[RomualdKratky]

I found a reliable workaround for this in a pnpm monorepo setup.

The Root Cause:
The @react-email/preview-server package (used by the CLI) ships with a pre-built .next directory. This directory has its own internal node_modules where esbuild@0.25.10 is bundled.

In a modern monorepo, your system (or other tools like Vite/Storybook) might provide a newer binary (e.g., 0.27.3). Because the bundled JavaScript in the .next folder is hardcoded to version 0.25.10, it fails the version check when it tries to call the newer system binary, even if your project-wide esbuild is correctly configured.

The Solution:
Since we can't easily reach into the pre-built .next folder via standard overrides, we can use a small "Sync Script" that runs before the preview server starts. It copies the correct (working) esbuild JavaScript files into the bundled directory of the preview server.

1. Ensure your desired version is forced in package.json

Add this to your root package.json to ensure consistency across the monorepo:

"pnpm": {
  "overrides": {
    "esbuild": "0.27.3"
  }
}

2. Create a fix script (e.g., scripts/fix-preview-esbuild.cjs)

This script synchronizes the bundled esbuild JS with your system's version:

const fs = require('fs');
const path = require('path');

// Identify the bundled esbuild inside the preview server
// Note: This path uses require.resolve to find the package regardless of hoisting
try {
  const targetEsbuildPath = path.join(
    path.dirname(require.resolve('@react-email/preview-server/package.json')),
    '.next/node_modules/esbuild'
  );

  // Identify your project's working esbuild
  const sourceEsbuildPath = path.dirname(require.resolve('esbuild/package.json'));

  if (fs.existsSync(targetEsbuildPath) && fs.existsSync(sourceEsbuildPath)) {
    console.log('🛠️ Syncing react-email bundled esbuild with system version...');
    
    const filesToCopy = ['lib/main.js', 'package.json'];
    
    filesToCopy.forEach(file => {
      const src = path.join(sourceEsbuildPath, file);
      const dest = path.join(targetEsbuildPath, file);
      if (fs.existsSync(src)) {
        if (!fs.existsSync(path.dirname(dest))) fs.mkdirSync(path.dirname(dest), { recursive: true });
        fs.copyFileSync(src, dest);
      }
    });
    
    console.log('✅ esbuild version mismatch fixed.');
  }
} catch (e) {
  console.log('⚠️ Could not find paths to patch. The preview server might still fail or is using a different structure.');
}

3. Update your dev script

Update your package.json (either root or the email package) to run the fix automatically:

"scripts": {
  "dev:email": "node scripts/fix-preview-esbuild.cjs && email dev"
}

This makes the fix portable across different machines and ensures that the "Host" (JS) always matches the "Binary" (System) whenever you start the preview.

[crudh]

@RomualdKratky nice find about the bundled .next folder being the root cause.

That folder should only be needed if the preview server is run in production mode. I wonder if it would be feasible to run it in dev mode instead and skip bundling the folder?

I did a quick test by:

• Cloning this repo
• Changing the preview server to run in dev mode here: https://github.com/resend/react-email/blob/canary/packages/react-email/src/utils/preview/start-dev-server.ts#L147
• Added esbuild@0.27.3 as a dev dep to the Playground app: https://github.com/resend/react-email/tree/canary/playground
• Installed & built everything
• Removed the .next folder from node_modules in the Playground app
• Started the Playground with pnpm dev
• Everything looked good

Can't say for sure this fixes the issue, but could be a possible way?

[gabrielmfern]

It might fix it, but it will make it much slower

[bsanchez-grupo-active]

@RomualdKratky solution works, but I had to explicitly install esbuild in the package where I have react-mail in my monorepo

[crudh]

thanks @gabrielmfern, all good now with the latest release!