@unlayer/react-elements 0.3.0: Tailwind, Markdown, code, fonts, async, codegen and editor-parity fixes

[ivoIturrieta]

What

The next @unlayer/react-elements release (0.3.0): a new render engine, formats developers already use, a design → code converter, and fixes so the HTML and the design that opens in the Unlayer editor always agree. No API is removed. One deliberate behavior change: a part that fails to render now fails the render (see below).

A new render engine

0.2 rendered templates with react-dom: one render collected the template through markers written into its HTML, then about 15 more rendered the rows. In Next.js App Router server code (two React copies) that broke: components using hooks were dropped and async emails came out with no rows, with only a warning.

0.3 walks the template itself and answers its hooks (useContext, useId, useMemo, use, …) as React's server renderer does. Elements never calls react-dom (it stays a peer dependency only because @unlayer/exporters imports it).

• Works where React works (tested): Node, the edge runtime, Next.js route handlers, Server Components and Client Components (webpack and Turbopack), React 18 and 19.
• Components run once per render; async siblings load in parallel and always land in tree order.
• Its HTML is react-dom's: the markup it writes matches react-dom/server's static markup for the installed React (18 or 19), byte for byte: form controls (<select value>, <textarea>, inputs), <style>/<script>/<title> text, attribute order, void elements. A differential test checks every element and attribute kind React treats specially (about 115,000 cases) and random trees, on React 18.0, 18.3 and 19.3. Four differences are deliberate and listed in that test: React 19 moving <title>/<meta>/<link> to the top, the <head> it adds to a bare <html>, function form actions, and a failure inside <Suspense>, which follows Elements' error policy. In <Head>, a <style>'s or <script>'s CSS and JS are written as given.
• Renders are isolated: a render's output and errors depend only on its own arguments. What it works out lives in its own scope, every public render starts a fresh one, and your code (components, wrappers, exporters, callbacks) runs outside it, so a render started inside another can't change it, and elements kept between renders can't carry anything over. A seeded test renders random pairs of templates that share hoisted elements, in both orders and at once, and checks each output never changes.
• Errors name the component and where it sits: [Unlayer] boom (in <Hero> at Row 3 › Column 1 › Hero), a RenderError with the original as cause. A failure throws by default, in the sync and async renderers alike; onError: "omit" (or a function) leaves the failed part out of the HTML, the text and the design alike and lists it in renderToHtmlParts().omitted. That covers every part: components, Rows and Columns, exporters, template wrappers, a custom tool's head, and what's in a <Head>.
• The design is the source of truth: the HTML is the exporters run on the design. The design no longer renders the HTML, so it's fast.
• React compatibility is checked, not assumed: a once-per-process self-check of React's internals; an unknown React that passes works, one that doesn't fails with "unsupported React x.y.z" (UNLAYER_SKIP_REACT_CHECK=1 to bypass). CI runs the suite on React 18.0, 18.2, 18.3, 19.1, 19.2 and 19.3 in dev and prod (and the release job publishes only after that matrix passes), compares useId with react-dom's own, and runs a weekly canary.
• useId() gives React's own ids (no internal prefix); idPrefix sets a prefix for emails embedded in a page.
• Divider, Html, Menu and Social write their web and document HTML as strings, byte-identical to the pinned exporters (a 12k-case test that's also the drift alarm), so pages and documents render on the edge too.
• packages/react/ARCHITECTURE.md explains the pipeline, the dispatcher, the error policy and the invariants.

New entries (separate imports, so the main bundle stays small)

Entry	What it gives you
/tailwind	<Tailwind>: classes become each component's props at render time, so the email gets inline styles and the design stays editable. Phone variants become phone settings, hover: becomes button hover colors, container text classes reach the text inside, card grids get gutters, and logical classes (ps-*, ms-*, border-s-*, rounded-s-*, text-start) follow the text direction. What it compiles stays bounded in a long-lived server (the last 50 configs; a fresh compiler past 2,000 classes).
/markdown	<Markdown>: Markdown becomes editable blocks. Raw HTML in it (html="sanitize", the default) is read once, as a browser reads it, and written back with only display tags and attributes (allowlists, URLs and styles checked), so nothing removed can rejoin into a tag; a fuzz test reads its output back with a real HTML parser.
/code	CodeBlock / CodeInline with highlight.js themes.
/font	<Font>: web fonts with fallbacks. The URL is kept in the design.
/head	<Head>: custom head tags. Components in it render as the template's do (context, async, onError).
/async	Async templates and components (React.lazy too), Suspense, and pretty output. A <Suspense> around the root is waited for: its fallback can't make a document, so it never becomes the email.
/codegen	designToElements(design): an Unlayer design becomes readable Elements code. The round trip is exact on 48 of 49 real designs and on fuzzed ones.

Main entry

• Link.
• style, className and skipInText on every component.
• Plain-text options and toPlainText.
• Prop aliases: Menu color, align/textAlign, Heading as/level. Close misspellings get "did you mean" warnings.
• values accepts partial objects with strict keys (ValuesInput).
• Rich inline JSX children.

HTML / editor parity fixes

• <UnlayerProvider config> now applies. The most specific setting wins: render options, then the root's config, then the Provider, then defaults. Safe in Server Components and on the edge.
• Paragraph text is stored as typed, so the editor no longer formats markup the email shows literally.
• Exact px image widths.
• Bare zeros are written as 0px in designs.
• The Row background-image fullWidth default agrees between HTML and design.
• The body link color applies in the HTML.
• url() values are percent-encoded.
• Right-to-left dir/lang on the body.
• A Row whose Column count doesn't match its layout fails the render with an error naming it (or is omitted with onError: "omit"), instead of blanking the email.
• Render errors keep their cause.
• Checked against the real editor (load, save and export 152 templates in the Unlayer editor): a Paragraph's HTML is now the editor's text block (a percent line height, no <p> wrapper), so lines with mixed text sizes no longer shift; a root's fonts reach the design; the document has the editor's base stylesheet for each mode; images and video thumbnails are sized in the block's slot (the default 10px padding), not the column; a fixed-width image's percent is the same in HTML and design; and the design records displayMode, so code generated from it picks the right root. A per-block test checks every block's HTML equals the editor's export of its design, in all three modes.

Row padding keeps the editor's meaning (outer padding, in email, web and print). Elements now warns when it sits outside a content background; use Column padding to inset. Tailwind p-* on a Row insets, as CSS does.

Validation

• Tests: react 1540, shared 126, convert-core 212, from-react-email 344, migrate 212. Typecheck, test:csp, test:browser-runtime, test:e2e, test:fidelity and test:differential pass. The React matrix (18.0.0, 18.2.0, 18.3.1, 19.1.0, 19.2.9, 19.3.1; dev and prod) passes.
• Same output as the 0.2 engine: 956/956 outputs byte-identical on React 18.3, 19.1 and 19.3 across the corpus (examples, patterns, showcase, the 152 editor round-trip templates, migrate outputs, i18n), and 45,000 random templates with 0 differences, apart from the intended changes (errors throw, clean ids, react-intl templates that 0.2 rendered without their translations now render fully).
• Visual: Storybook builds and test:visual matches on 138 stories × 2 viewports. The baseline was regenerated after attributing every changed render to intended changes (exact image widths, the Provider fix, the text block's markup, images sized in their slot).
• Integrations: the packed tarball builds and verifies in the Next.js 14, 15 (webpack and Turbopack) and 16 apps and the Jest 30 app: route handlers, Server Components, Client Components, async routes and pages, App Router and Pages Router edge routes, with hooks used after Elements' renders.
• Speed (median, production, vs 0.1.22): renderToHtml 0.97–0.99×, renderToPlainText about 0.96×, renderToJson 1.3–1.45× (0.11 ms for a 12-row email); against 0.2's engine, HTML takes about half the time and JSON about a third.
• Bundle: the main entry is 198,363 / 198,500 bytes unminified (it now carries Elements' own renderer and HTML writer instead of using react-dom's).
• Real editor round trip (152 templates: feature tests, showcase, CLI starters, all docs patterns and starters, MJML and Beefree imports; editor 1.524.0, re-run on the new engine with 1.526.0 with identical results): every design loads, saves and exports with nothing lost, and the code generated back from it type-checks and gives the same design. Elements' HTML looks identical to the editor's export on desktop for 134/152 (115 before these fixes). The rest are the editor's own behavior (its stylesheet for Google fonts it lists, phone settings that need mobile design editing), the HTML-only props, or the newer editor's page margin for documents. The one Elements difference left is sub-pixel: a fixed-width image keeps the exact px the author asked for (64px), where the editor derives 63.97px from the design's percent.
• Tailwind accuracy, measured against real Tailwind 4.2.1 in Chrome on 263 classes: 96.9% render like Tailwind in email and 95.7% on web; 168/170 colors are byte-exact; line heights are within 0.5px.

Release notes

• Releases as 0.3.0 (minor): a new engine, new entries and changed HTML output, no removed API. Failures now throw by default (onError: "omit" keeps omission, listed); the upgrade guide in the guides PR covers it. The version is committed in packages/react/package.json, which the release job publishes instead of its default patch. Without it, this would ship as 0.2.2 to every ^0.2 project.
• @unlayer/migrate's Elements range goes to ^0.3.0 here. The release job refuses an Elements outside the published migrate's range, so migrate then republishes after it (0.1.3, the same converter) and asks projects on 0.2.x to upgrade first.
• The CHANGELOG lists everything new in 0.3 (every new entry, <Link>, style/className, the plain-text options, inline JSX), what changed, and the history from 0.1.1 to 0.2.1.
• After publishing, move the @unlayer/react-elements-previous alias to 0.3.0.

---

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

[codecov]

Codecov Report

❌ Patch coverage is 97.17095% with 141 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.83%. Comparing base (eb0a80d) to head (bc81fd5).

Files with missing lines	Patch %	Lines
packages/react/src/engine/walk.ts	91.19%	37 Missing ⚠️
packages/react/src/engine/dispatcher.ts	85.54%	25 Missing ⚠️
packages/react/src/markdown/Markdown.tsx	93.61%	12 Missing ⚠️
packages/react/src/codegen/blocks.ts	96.68%	8 Missing ⚠️
packages/react/src/engine/tree-id.ts	76.47%	8 Missing ⚠️
packages/react/src/async/index.ts	86.27%	7 Missing ⚠️
packages/react/src/codegen/test-harness.ts	95.10%	7 Missing ⚠️
packages/react/src/codegen/device.ts	89.65%	6 Missing ⚠️
packages/react/src/codegen/design-to-elements.ts	96.11%	4 Missing ⚠️
packages/react/src/codegen/print.ts	97.54%	4 Missing ⚠️
... and 10 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #69      +/-   ##
==========================================
+ Coverage   96.55%   97.83%   +1.28%     
==========================================
  Files          40      122      +82     
  Lines        2789     8466    +5677     
  Branches      795     2999    +2204     
==========================================
+ Hits         2693     8283    +5590     
- Misses         95      183      +88     
+ Partials        1        0       -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.