react-email-studio 3.8.1 → 3.8.2

package/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.8.2] - 2026-05-22
+
+### Added
+
+- Added **`RELEASE.md`** as a single-file release tutorial and included it in the published npm package.
+
+### Fixed
+
+- **Text block newline handling** is now consistent in canvas preview and exported HTML: plain text line breaks render as `<br/>`, while HTML content remains passthrough.
+
 ## [3.8.0] - 2026-05-15
 
 ### Changed

package/README.md

@@ -7,7 +7,7 @@
 
 ## Release notes
 
-**Latest: 3.8.0** — export uses **`rows[]`** + **`_reactEmailStudio`** (LMS shape); palette blocks add as root sections; section reorder via drag handle or inspector.
+**Latest: 3.8.2** — includes a single-file **`RELEASE.md`** npm tutorial and fixes plain text newline rendering parity between canvas preview and exported HTML.
 
 Version history and migration hints: **[CHANGELOG.md](./CHANGELOG.md)** (also included in the published npm tarball under `node_modules/react-email-studio/CHANGELOG.md`).
 
@@ -121,7 +121,8 @@ Implement **`onUpload`** so image/video uploads return URLs your recipients can
 | `ReactEmailEditorOptions`, `JsonToHtmlOptions`, `EmailHtmlOptions` | Editor options and HTML generation options. |
 | `EmailDocument`, `EmailDocumentSettings`, … | JSON schema types for stored designs. |
 
-For framework setup (Next.js client/SSR), props tables, and troubleshooting, see **[TUTORIAL.md](./TUTORIAL.md)**.
+For a single-file release tutorial, see **[RELEASE.md](./RELEASE.md)**.
+For extended framework setup (Next.js client/SSR), props tables, and troubleshooting, see **[TUTORIAL.md](./TUTORIAL.md)**.
 
 ---
 

package/RELEASE.md

@@ -0,0 +1,137 @@
+# react-email-studio release tutorial (single file)
+
+Use this file as the one-stop guide for npm integration, save/load, HTML export, and API usage.
+
+## Install
+
+```bash
+npm install react-email-studio
+```
+
+Install peer dependencies in your app:
+
+- `react`, `react-dom`
+- `lucide-react`
+- TipTap v3:
+  - `@tiptap/react`
+  - `@tiptap/core`
+  - `@tiptap/starter-kit`
+  - `@tiptap/extension-link`
+  - `@tiptap/extension-placeholder`
+  - `@tiptap/extension-text-align`
+  - `@tiptap/extension-text-style`
+  - `@tiptap/extension-underline`
+
+## Minimal integration
+
+```tsx
+import { useRef, useCallback } from "react";
+import {
+  ReactEmailEditor,
+  type ReactEmailEditorRef,
+  jsonToHtml,
+} from "react-email-studio";
+
+export function MailStudioPage() {
+  const ref = useRef<ReactEmailEditorRef>(null);
+
+  const save = useCallback(() => {
+    ref.current?.exportJson((jsonString) => {
+      void fetch("/api/email-designs", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ design: jsonString }),
+      });
+    }, true);
+  }, []);
+
+  return (
+    <>
+      <button type="button" onClick={save}>Save design</button>
+      <ReactEmailEditor
+        ref={ref}
+        hideTemplates
+        onUpload={uploadImageAndReturnUrl}
+        onReady={(api) => {
+          // api.loadJson(savedDesignJsonOrObject);
+        }}
+      />
+    </>
+  );
+}
+
+async function uploadImageAndReturnUrl(file: File): Promise<string> {
+  const body = new FormData();
+  body.append("file", file);
+  const res = await fetch("/api/upload", { method: "POST", body });
+  const { url } = await res.json();
+  return url as string;
+}
+
+export function htmlFromStoredDesign(designJson: string): string {
+  return jsonToHtml(designJson);
+}
+```
+
+Important: `onUpload` must return public HTTPS URLs that recipients can access.
+
+## Next.js note
+
+The editor is client-side. Use:
+
+```tsx
+"use client";
+```
+
+If needed:
+
+```tsx
+import dynamic from "next/dynamic";
+const ReactEmailEditor = dynamic(
+  () => import("react-email-studio").then((m) => m.ReactEmailEditor),
+  { ssr: false },
+);
+```
+
+## Core API
+
+- `ref.loadJson(input)`:
+  - Accepts JSON string or object.
+  - Replaces editor content.
+- `ref.exportJson(cb, pretty?)`:
+  - Returns canonical `email_document` JSON.
+- `jsonToHtml(design, opts?)`:
+  - Converts design JSON to full HTML document.
+- `htmlToJson(html, pretty?)`:
+  - Converts pasted HTML to `email_document` JSON.
+
+## Exported helpers
+
+- `htmlToEmailDesignTemplate`
+- `extractHtmlForDesign`
+- `canonicalizeEmailDocument`
+- `utf8ToBase64`, `base64ToUtf8`
+- `EmailPreviewModal`, `emailPreviewDevices`
+
+## JSON storage shape
+
+Persist `exportJson` output as your source of truth:
+
+- `type: "email_document"`
+- `settings`
+- `rows[]` (preferred export shape)
+  - row `layout`, `styles`, `columns[].blocks[]`
+  - `_reactEmailStudio` metadata for editor round-trip
+
+Import supports legacy `blocks[]` and older styles, but export writes `rows[]`.
+
+## Troubleshooting
+
+- Missing module errors: install all peers with compatible versions.
+- Blank HTML from `jsonToHtml`: invalid/empty design input.
+- Broken email images: `onUpload` URL is private, local, or expired.
+- SSR errors: ensure client boundary (`"use client"` or dynamic `ssr: false`).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -872,6 +872,11 @@ function escHtmlAttr(s) {
 function escHtml(s) {
   return String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
+function textBlockContentToHtml(content) {
+  const raw = typeof content === "string" ? content : "";
+  if (/^\s*<[^>]+>/.test(raw)) return raw;
+  return escHtml(raw).replace(/\r?\n/g, "<br/>");
+}
 function utf8ToBase64(raw) {
   const bytes = new TextEncoder().encode(raw);
   let bin = "";
@@ -1212,8 +1217,7 @@ function blockToHtml(cb) {
     case "text": {
       const shell = emailSurfaceBgCss(p);
       const inner = `font-size:${lenPx(p.fontSize)};color:${p.color};text-align:${p.align};font-weight:${p.fontWeight || 400};font-style:${p.italic ? "italic" : "normal"};text-decoration:${p.underline ? "underline" : "none"};line-height:${lh(p.lineHeight)};letter-spacing:${lenPx(p.letterSpacing)};font-family:${p.fontFamily || "Georgia,serif"}`;
-      const content = typeof p.content === "string" ? p.content : "";
-      const body = /^\s*<[^>]+>/.test(content) ? content : escHtml(content).replace(/\r?\n/g, "<br/>");
+      const body = textBlockContentToHtml(p.content);
       return `<div style="${pd(p.padding)};${marginCss()}${shell}"><div style="${inner}">${body}</div></div>`;
     }
     case "html": {
@@ -3052,7 +3056,7 @@ function ContentBlock({ block, selected, onClick, preview, C }) {
       "div",
       {
         style: { fontSize: p.fontSize, color: p.color, textAlign: p.align, fontWeight: p.fontWeight || (p.bold ? 700 : 400), fontStyle: p.italic ? "italic" : "normal", textDecoration: p.underline ? "underline" : "none", lineHeight: p.lineHeight || 1.65, letterSpacing: `${p.letterSpacing || 0}px`, fontFamily: p.fontFamily || "Georgia,serif" },
-        dangerouslySetInnerHTML: { __html: p.content }
+        dangerouslySetInnerHTML: { __html: textBlockContentToHtml(p.content) }
       }
     )
   );