React Email → Elements migration (@unlayer/migrate)

[ivoIturrieta]

A one-command path from React Email (@react-email/components) to Elements. Users keep their templates and gain visual editing in the Unlayer editor, plus web and PDF output. It also gives coding agents a clear route to Elements.

npx @unlayer/migrate ./emails --report migration.md   # convert and check, write nothing
npx @unlayer/migrate ./emails --write                 # replace the templates
npx @unlayer/migrate compare <original> <migrated>    # check a template converted by hand

The PR has two parts, and each commit passes the full test suite on its own:

1. Elements rendering fixes. Building the converter turned these up.
2. The converter, the CLI and docs (including the packaging change).

1. Elements rendering fixes

• <Row noStackMobile> now keeps columns side by side on phones. It had no effect, for two reasons:
  • The exporters read "do not stack on mobile" only from the row's mobile override (_override.mobile.noStackMobile), where the editor saves it. mapSemanticProps now writes it there.
  • A later row's .u-row .u-col rules overrode an earlier row's .no-stack rules of the same specificity. The no-stack rules now use .u-row.no-stack.
• rgb() colors render. The exporters turned rgb() into #NaN… in Outlook's bgcolor, and Tailwind writes every color as rgb(). Colors are now written as hex, or rgba() when translucent.
• Font names in double quotes no longer break the style attribute. They're written with single quotes.
• previewText is escaped. Markup in it, often user data like a name, could end the hidden preheader.
• Root components accept fonts ([{ url }]). renderToHtml links them in the document head.
• Root components accept textDirection and lang. renderToHtml puts both on <html>; the direction also reaches the content and the design JSON, as the editor stores it.
• Phone settings match the editor's device CSS. mobile accepts padding, text size, line height, alignment, image/button width and column borders. Rows and content also accept hideOnMobile and hideOnDesktop; columns don't, as in the editor. Four small editor exports are saved as CSS parity fixtures.
• Bundle budget is now 86KB. The ESM bundle is 85,559 bytes.

Behavior changes:

• Rows with noStackMobile stop stacking on phones.
• Design JSON saves it as _override.mobile.noStackMobile.
• Markup and entities in previewText show as typed ("Fish & chips", not "Fish & chips").
• Designs with _override.mobile now render their phone settings at the editor's 480px breakpoint.
• renderToJson keeps phone settings and visibility flags. Every stacked column gets the box's phone side padding.

2. React Email migration

Packages

@unlayer/migrate is the one published migration package. It provides the CLI and the react-email subpath.

The CLI (npx @unlayer/migrate):

• It runs in the user's project, with their React, React Email and tsconfig paths.
• It writes nothing until asked to (--write or --out). All templates are converted and checked before output is written; --write leaves files imported by another scanned file unchanged so failed or other importers can keep using them.
• --design writes design JSON for loadDesign(), with text props as merge tags ({{name}}).
• --report writes the report in Markdown or JSON.
• The exit code is 0 when every template passes and 2 when one fails, so it fits in CI.

The library (@unlayer/migrate/react-email):

• Codemod (convertSource) keeps props, .map() loops, conditions and PreviewProps, and inlines the project's own components.
• Runtime (convertReactEmail) renders a template for the visual editor, with text props as merge tags.
• verifyConversion checks a migrated template against its original.

Open in the editor. --design makes any React Email template an Unlayer design for loadDesign(). Spacing between sections becomes row and column padding instead of empty rows (472 → 81 across the benchmark), and a column that only holds space gets an invisible zero-height divider. The editor draws every empty column as a "No content here" placeholder that stretches its row, so migrated designs used to open looking broken; now none of the 106 has an empty column, and the sent email is unchanged. The editor loads and exports a web font only when it's registered when the editor is created, so the JSON report lists each template's fonts in the editor's fonts.customFonts shape (the library returns them too). Blocks kept as HTML state their font size, and images in text and HTML blocks state their width in their style, since the editor's canvas would otherwise show the blocks at 14px and the images at their file's size. examples/react-email-in-editor runs it end to end: it migrates templates and opens them in the hosted editor, and the docs and agent rules link to it.

@unlayer/from-react-email and @unlayer/convert-core are private workspace packages, bundled into migrate. Convert-core holds the shared Elements tree, report, TSX printer and content check.

How each conversion is checked. The original and the migrated template are rendered with PreviewProps, then again with each boolean prop flipped. Every word, link, image and alt text must still be there, and renderToJson must get every block. No words may be added, including when a boolean prop is flipped. A template that fails isn't written. What Elements can't express natively stays as an Html block that renders as before, and unsupported features and dropped styles are in the report.

Results

Measured on 106 templates: React Email's own demos, MIT community templates and agent-written ones. Details are in packages/from-react-email/FIDELITY.md, and pnpm --filter @unlayer/from-react-email bench reruns the benchmark.

	Codemod	Runtime
Convert and type-check	106 / 106	106 / 106
Lose or add a word, lose a link or image	0	0
Native (editable) content	98.4% (96 fully native)	98.4% (97 fully native)
Words out of place on desktop: median / mean	0% / 0.9%	0% / 1.1%
Words out of place on phones: median	0% (was 16.5%)	0% (was 13.9%)

All 212 conversions keep exactly the baseline word coordinates at both 700px and 375px.

All 106 designs were loaded into the hosted editor (fonts registered from the report), saved and exported. All open with no errors, and the editor keeps every value the design sets. The editor's exported HTML puts every word exactly where Elements' HTML does for 98 of the 106. Of the other 8, two have real differences: an HTML block's paragraphs lose their spacing (the editor's CSS resets p margins), and Dropbox's text shows in Open Sans, which the template names but never loads; the editor has it built in. In three, a line or two shifts by 2–5px because the hosted editor writes 140% line heights where Elements writes 1.4. In three Barebone templates a few words wrap differently: their 420-weight text is drawn with a 450 face that another template's font list adds when all fonts are registered in one editor.

Five converted designs were loaded into the editor, saved and exported. Every row, border, button width and no-stack setting came back unchanged. Two more designs with phone settings (90 elements) were loaded, saved and exported: every setting came back unchanged, and the editor's export applied them.

Known differences:

• Column vertical alignment: email columns sit at the top.
• Unsupported state variants, unresolved utilities, phone font weight and letter spacing remain in the report.
• Phone settings use the editor's 480px breakpoint; source queries can use 600px. Narrow-box decisions use 375px.
• Image border radius is dropped.
• On phones, columns side by side keep their share of the row (icon gaps scale with the screen). Text whose longest word wouldn't fit gets a smaller phone size; words inside Html blocks can still break.
• Painted cards stacked inside a column lose their own background and border (Elements paints a column once).
• Shadows and gradients are dropped.
• A small bordered box beside text (a numbered step badge) becomes a bordered column as tall as its row.

Testing

• Tests: 783 passed: shared 99, react 496, convert-core 24, from-react-email 105, migrate 59. The packed consumer test checks the library in ESM and CommonJS, runs the installed CLI (with its own React 19) against a React 18 project, and checks that it stops on an Elements release older than it supports.
• Elements checks: browser E2E checks phone padding, image width and visibility at 375px in email and web, with negative controls. The 12 editor CSS comparisons pass. Storybook smoke passes all 138 stories; visual drift passes at 2 widths, with all 137 existing stories unchanged. CSP, browser runtime, coverage and the packed Next.js integration build pass.
• Node: tested on Node 22 and Node 25. The built CLI was also run end to end in a separate project.

Releasing

The release workflow now publishes each package only when its code changed since its last release tag (Elements v*, migrate migrate-v*), each behind the existing approval. Merges that change neither publish nothing.

• Elements 0.2.0. packages/react/package.json is set to 0.2.0: this release changes behavior (noStackMobile works, previewText is escaped), and a version committed ahead of npm now wins over the automatic patch bump. Packing migrate turns its workspace:^ dependency into ^0.2.0, so it can't install the old 0.1.x, which lacks the settings the converter writes.
• Migrate publishes after Elements, checks that the Elements range it requires is on npm, and tags migrate-vX.Y.Z (releases not marked latest). Until its first version is on npm, the workflow skips it with a notice.
• The CLI also stops (exit 1, with the install command) when the project's Elements is older than the range it supports.

After merging:

1. Approve the run: Elements 0.2.0 publishes.
2. Publish @unlayer/migrate 0.1.0 by hand from main (pnpm pack in packages/migrate, then publish the tarball with public access), and push the tag migrate-v0.1.0 on that commit.
3. On npmjs.com, add the trusted publisher for @unlayer/migrate: repository unlayer/elements, workflow publish.yml, environment npm-publish.
4. Run npx @unlayer/migrate on a sample template in an empty folder.

Not in this PR

• The first @unlayer/migrate release. npm adds a trusted publisher only to an existing package, so its first version is published by hand (see Releasing).
• Output has been checked in Chromium only, not in real email clients.
• MJML as a second source format.

🤖 Generated with Claude Code

---

📖 Storybook Preview: https://unlayer.github.io/elements/pr/61/

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.77%. Comparing base (b3d4e7b) to head (49d1610).

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #61      +/-   ##
==========================================
+ Coverage   95.54%   95.77%   +0.22%     
==========================================
  Files          32       33       +1     
  Lines        1975     2082     +107     
  Branches      390      454      +64     
==========================================
+ Hits         1887     1994     +107     
  Misses         87       87              
  Partials        1        1              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.