Migrating to v3

Migrating to Version 3.0.0

Version 3.0.0 of jsx-email modernizes the runtime, package exports, preview app, and CLI. It also removes the v1 compatibility escape hatch that was deprecated during the v2 cycle.

This guide was compiled from the next/v3 branch history, the PRs merged into next/v3, and the v2 migration guide.

Quick Checklist

Breaking Changes

Node.js 22 Minimum

All v3 packages set the minimum Node runtime to >=22.0.0. Upgrade local development, CI, deployment images, and package manager toolchains before upgrading jsx-email.

{
  "engines": {
    "node": ">=22.0.0"
  }
}

React 19 Peer Dependencies

The v3 branch targets React 19. Projects should move to React and React DOM ^19.1.0.

npm install jsx-email react@^19.1.0 react-dom@^19.1.0

TypeScript projects should also update React types to the matching v19 range.

ESM-only Package Entrypoints

All jsx-email related packages, including plugins, are now ESM-only. While this is a breaking change, v3 also requires Node 22+ which now has compatibilty for requireing ESM modules. So there should be no fundamental changes to make, only something to be aware of.

If your project is still CommonJS, please consider migrating to ESM-only.

Butan Has Been Removed

The v2 migration guide marked Butan as deprecated and stated that it would be removed in the next major version. In v3, Butan is no longer exported from jsx-email.

Before:

import { Butan } from 'jsx-email';

<Butan href="https://example.com" style={{ padding: '10px 20px' }}>
  Click me
</Butan>;

After:

import { Button } from 'jsx-email';

<Button
  href="https://example.com"
  width={160}
  height={44}
  backgroundColor="#111827"
  borderRadius={6}
  textColor="#ffffff"
>
  Click me
</Button>;

The current Button component is the supported path and is designed around explicit email-safe props rather than relying primarily on CSS styles.

create-mail Replaces the Old Create Package

Use create-mail for new projects. The v3 scaffold targets Node 22 and includes React 19 and React DOM 19 in generated project dev dependencies.

npx create-mail my-email-project

Raw and Conditional Rendering Changed Internally

The public component APIs remain the same, but the renderer now uses a rehype-based pipeline for Raw and Conditional output. This can change rendered HTML details and snapshots.

Review output if you rely on exact HTML strings. The v3 behavior includes:

CLI Changes

--use-preview-props Works for build and check

email build and email check both support --use-preview-props. When set, the CLI uses the template’s exported previewProps instead of separately supplied props.

email build ./emails --use-preview-props
email check ./emails/welcome.tsx --use-preview-props

check Supports --email-clients

email check can limit compatibility validation to a comma-separated list of email clients.

email check ./emails/welcome.tsx --email-clients gmail,outlook

The v3 check command remains caniemail-based.

New Components

These additions do not require migration, but they are new in v3 branch work and may replace custom code in your project:

Package-level Notes

jsx-email

create-mail

References