@unlayer/elements-preview: a local preview for Elements templates - #72

Stacked on the 0.3.0 library PR (#69): it shows only the preview. Merge it after #69, with its base changed to main first. The repo's tests only run on pull requests into main or develop, so CI starts here once the base is main; until then, the validation below was run locally, with #69's head 06a1825 merged in.

What

@unlayer/elements-preview 0.1.0 is a local preview for Elements templates, like React Email's email dev. It's a dev dependency of a project: npm install -D @unlayer/elements-preview && npx elements-preview dev.

• dev:
  • previews a folder of templates with live reload, rendering them with the project's own Elements and React (Vite SSR with the project as root, so its imports, aliases and React resolve as in the app);
  • one top bar with Preview · Editor · Code, desktop/phone, dark mode, Checks and Copy for AI; the HTML, plain text and design JSON are copied and downloaded from their Code tabs (there's no Export menu);
  • every view, the checks and Copy for AI show only the selected template's render: right after a switch to a slow template they say it's rendering, so nothing of the previous template is copied, downloaded or checked under the new name;
  • when the server comes back after a restart, the page fetches the templates again and renders the selected one;
  • the Editor view opens the design in the Unlayer editor;
  • the checks drawer covers render problems, email-client support with source lines (caniemail), and links and images (an image with empty alt text is still requested, so a broken one shows);
  • the sidebar and the browser tab show Unlayer's logo, inline, so a static build under any path needs nothing more.
• Render timeout: a template has 30 seconds to load and render (--render-timeout <seconds> on dev, check, render, export, screenshot and build). One that waits forever fails as a template that throws (the preview and a build show it, check counts it as to fix, and check, render, export and screenshot exit with 1), and the next template renders right away instead of the whole preview freezing. A one-off command that's done while such a render still runs exits once its output is written out, rather than waiting for the render.
• Console capture: what a template, or a module it imports, logs while it loads (dotenv does) is reported with its other console output, so check --json and render --json print only JSON.
• export: HTML, plain text and design JSON files.
• build / start: a static preview to share or host. A build replaces its previous build's files (listed in .elements-preview-build.json) and leaves others alone; it refuses a non-empty folder that isn't a preview build.
• check [--json]: a "to fix" / "to check" report with exit codes, for agents and CI.
• screenshot: desktop, phone and dark PNGs using the system browser (puppeteer-core; no download).
• render --json: one template's HTML and design.
• Copy for AI: a button next to Checks that turns a template and its problems into a prompt.
• Security: binds to localhost and checks Host and Origin.

It's a package of its own, not part of the Unlayer CLI: it has to run in the project, with the project's Elements and React, and its dependencies (Vite, a Chrome driver, email-client data: about 110 MB) would quadruple the CLI's install for everyone.

Publishing

• Peers: @unlayer/react-elements >= 0.2.0 and React 18 or 19.
• The first version is published by hand (npm's trusted publishing needs the package to exist), tagged preview-v0.1.0, with its trusted publisher added. After that, the new publish-preview job in publish.yml publishes a change under packages/preview after a reviewer approves, without waiting for an Elements release.

Validation

With #69's head b35cc79 merged in (the merges had no conflicts; since 11ec4e2 they bring #69's fixes from four more review rounds (an email service's tags kept whole in rich text, background URLs and plain text's headings; display conditions written around rows and blocks; rich text's sanitizer tightened; a Table's cells from data written as text; style values' double quotes kept), and before them: every timing test in the react and shared packages through one helper (a cost at two sizes timed again where it looks slow, each size's fastest of three samples of 20 ms at least; a cost against a limit run twice more where it's over, held to the limit times the machine's measured slowness), after one more CI flake on a 5 ms baseline; and the streamed-context test's page data released once its shell is written, not on a timer that React 18's setImmediate-scheduled shell could lose to; the round before: Tailwind's stylesheet, which each build reads again whole, read in time linear in its size on Node 20 (a compiler's of 2,400 classes, 114 KB, took 118 ms a build, now 5.6 ms); the Tailwind class growth fuzz retimed, with the one variant shape Tailwind's own compiler reads in time squared left out and read at the 512-character cap under 100 ms; the round before: tests that hold on CI's runners (a turn of the event loop between tests, so vitest's report of them can't time out; the Tailwind swap test's stylesheets read where Elements reads them; the growth tests time a shape that looks slow again, then at ten times the size, and each quote against a quarter of its size; the deep code test within Node 20's stack; 30 s a test), and docs that say what ships (moduleResolution: "node" needs skipLibCheck, an image's source is written as given, a prop leaves out a url() in double quotes); the round before: markup's inline styles hold what an escaped style can (a theme's double-quoted font names, url("…"), a string's ;), and refuse only what could end the attribute or start a tag once read, or a URL a component can't take (url(javascript:…)); a render's shared work is kept across copies of Elements and in all the code it runs; plain text leaves out blocked URLs and keeps its placeholders from text that decodes to them; text placed straight in a Row or Column is said once per render; the main entry's budget is 221 KB; the round before: a handle keeps a fresh Tailwind compiler ready, so a synchronous loop of renders gets one at once, and past 8,000 classes on one compiler with none ready a render that needs a new class fails saying to yield or use the async renderers; markup inlines no class value a prop can't take; a render's shared work is kept to its own render (template wrappers, nested renders) and Markdown's table cells count against it; code themes are read by their own names; plain text's skip names are read as written; the main entry's budget is 219.5 KB; the round before: Tailwind's shared compiler is given only classes it builds in time (512 characters, 8 variants, 4 & in a class's variants, brackets 8 deep, a render's 64 KB of classes), and a class its build throws for without keeping it is found and left out; a Markdown's headings' and rich text children's classes are compiled with the render's others; an image's size string is read once; Markdown's and code's work is shared across a render, not per block; plain text's tag names are indexed by their parts; the main entry's budget is 218 KB; the round before: a content prop given as null renders nothing, as in 0.2.1; a logo's height class keeps its shape; a Video's id can't add markup; Tailwind classes, rich text's markup, HTML's plain text, code's trailing whitespace, and Markdown's would-be tables, link text, list items, paragraph lines and references are read in time linear in their size; the main entry's budget is 216 KB; the round before: a Tailwind plugin's error is tied to its class by the value Tailwind gave the function, so a user's class can't fail the app's own; Tailwind classes in a Heading's or a Button's children and on a lone <Link> are inlined; a prop given as null is one not given; a <script>'s or <style>'s text in rich text children is left out; a Row's anchor, a Video's link and thumbnail and a Social icon's image can't add markup; a Font's javascript: URL loads nothing; highlight.js's time is bounded; Markdown's quotes and task lists and designToElements() take time linear in their size; the main entry's budget is 207 KB; the round before: Markdown's inline syntax from data is read in time linear in its size; a Tailwind plugin's function that gives nothing, or an @apply Tailwind can't compile, no longer breaks the shared handle, and an error that can't be tied to a class fails only its render; an async render that renders again lists and says each part it leaves out once; the docs say a Table's cells are HTML and style props are written as given, and the Markdown guide gives its densest shapes' output, time and memory; the round before: a block's link is read with its character references decoded (javascript:, javascript:), in every shape, so no javascript: link the editor's exporters write runs; a Tailwind plugin's error is pinned on its class where another utility gives the class CSS too and inside compound variants, in every render; an async render whose own class makes Tailwind compile again renders again once it has; the Markdown guide gives memory for its worst shape, deeply nested quotes; the round before: a Tailwind plugin that throws for one class fails only the component whose class it is and changes nothing in other renders; the links the editor's exporters write get a javascript: URL as one that throws; a null Menu item or Social icon is skipped; and before that: a javascript: URL in the links Elements writes is one that throws with React 18 too; a render reads its first 2,000 different Tailwind classes; only the Tailwind class built alone and seen to fail is refused; a <Tailwind>'s own classes are built at once; a cid: or base64 image url() is kept; a link of null is none (none of them touch the preview's code); and before them, fixes for hostile inputs, Markdown's size limits, very long Markdown, Markdown and Tailwind classes from data rendering in time linear in their size, and what a context reads around an app's renders):

• Elements now writes a javascript: link's URL (the needs-fixes template's Button) as the one react-dom 19 writes, which throws: check still finds it to fix, with that URL, and its tests and render --check's expect it.
• preview 99 tests and tsc pass, and so do the other packages' tests (react 1,894, from-react-email 344, convert-core 212, migrate 212, shared 142). New coverage: a template that never finishes (dev, check, export), console output while a template loads (check, render), an image with empty alt text requested, the live-reload test editing text the footer has, the app driven in a browser (only the selected template's render shown, the templates fetched again when the server is back), and output written out to a slow pipe before a command exits.
• A replay of the repo's CI workflow on a clean checkout passes every step (the preview's tests run in its pnpm test; the packed preview has its LICENSE).
• @unlayer/react-elements 0.3.0: Tailwind, Markdown, code, fonts, async, codegen and editor-parity fixes #69's last fixes are packaging and types (its LICENSE, CommonJS and node10 types, no highlight.js in the code entry's types, and its optional peers tailwindcss and prettier of any version, so a project's Tailwind CSS 3 or prettier 2 doesn't fail npm install); the preview's publish job and CI's pack steps now fail where its tarball has no LICENSE, as Elements' and migrate's do (the packed preview has one). With this head's packed Elements and preview, the fresh project's check --json gives the same results and export byte-identical HTML.
• End to end with the packed Elements 0.3.0 and preview in fresh projects, with React 19 and React 18 (identical HTML and designs), on the showcase templates (Tailwind, fonts, Markdown, code, shared components) and templates broken on purpose: check --json (findings, the failing component's RenderError with its source line, exit codes), render --json (designs carry displayMode, paragraphs are the editor's text block), export --design and build.
• Before the merge, on an earlier 0.3 build: screenshot --all (PNGs looked at), start, and dev in a browser (live reload, Preview / Editor / Code, desktop/phone, dark mode, checks, the Editor view in the Unlayer editor with local images; no console errors).