RFC: extension points for the preview (extra source tabs, a post-render hook)

[gazjones00]

Goals

1. Let a project add to the preview server without forking or patching @react-email/ui. The first two places are extra tabs in the source view, and a step that runs on the rendered markup before the preview shows it.
2. Keep format-specific output out of React Email itself, in line with Would the project be open to a contribution which adds support for shopify email templates #1374, while making it possible to build in userland.
3. Agree on a shape small enough to land and keep stable, before anyone writes code.

Background

We build Shopify notification emails with React Email, in several locales. Like #1374, the templates emit Liquid through a few small primitives (<Liquid.If>, liquid('order.name'), and so on), and a script exports each template per locale as the Liquid that gets pasted into Shopify. That part works well. The preview is where we've run out of room:

• We can't show the output we ship. The HTML tab shows the render, but our export does more. It decodes the entities React adds inside Liquid tags, so {{ 'now' | date: '%Y' }} survives. It runs pretty() with an unlimited printWidth, because Prettier breaks Liquid string literals at 80 columns. And it prepends a few {% assign %} config lines. So what the HTML tab shows isn't what we paste into Shopify. A "Liquid" tab next to React / HTML / Plain Text is the natural place for it.
• We hydrate the preview from inside the template. To show real-looking content instead of raw {{ }} tags, a higher-order component renders the template in isolation with @react-email/render, decodes entities inside the tags, runs LiquidJS over the result with mock data, and passes the string back to React through use(). It's a render inside a render, and it exists only because there's no step between "the template rendered" and "the preview shows it".

What we tried. Patching @react-email/ui (6.9.0) to add the tab. The code side is small: the tabs are a fixed markups array in src/app/preview/[...slug]/preview.tsx, and their content comes from render-email-by-path, which already reads PreviewProps off the template. But email dev starts Next from the package's prebuilt .next with dev: false, so a patch to src/ does nothing until the UI is rebuilt after every install. The patch also has to be regenerated on every release, because the CLI requires the UI version to match exactly. We decided that's not something we can maintain, which is what prompted this thread.

Related threads. #1044 (the 2023 addons RFC) asked for preview controllers and stalled on where a config would live. #1374 was told Shopify support is out of scope, but that a package would make sense, and this would let such a package exist. #3716 covers form controls for preview props.

Proposal

Template-level statics, following the PreviewProps convention. No config file and no plugin loading. The preview server already reads one static off the default export, so this adds two more:

MyEmail.PreviewSources = async (props) => [
  {
    label: 'Liquid',
    extension: 'liquid',
    language: 'html', // syntax highlighting only
    content: await toLiquid(<MyEmail {...props} />),
  },
];

MyEmail.PreviewTransform = async (markup, props) =>
  liquid.parseAndRender(markup, mockData(props));

• PreviewSources runs on the server in render-email-by-path, next to the existing markup / plainText renders. The results travel in the rendering metadata and show up as extra tabs. Copy and download keep working, using extension for the file name.
• PreviewTransform changes only what the preview iframe displays. It doesn't touch what render() returns anywhere else, and it doesn't feed the React tab.
• Failures stay contained. A throwing source shows the error in its own tab, and a throwing transform falls back to the untransformed markup with a warning. Neither blanks the preview.
• Static builds. email build would run both at build time with PreviewProps, so built previews get the tabs too.

Open question: per template or per project? Liquid hydration is the same for every template, so wrapping each one in a higher-order component, as we do today, is repetitive. Options:

• (A) Template statics only, as above. Smallest, explicit, and consistent with PreviewProps. Projects share behaviour by wrapping templates.
• (B) A project-level preview config (say emails/preview.config.ts) exporting sources and transform, applied to every template. Less repetition, but it brings back [RFC] Addons #1044's question of how the config is found and loaded.
• (C) (A) first, (B) later, using the same function signatures so moving from one to the other is mechanical.

I'd propose (C). (A) is useful on its own, can't affect anyone who doesn't opt in, and leaves (B) as an additive change.

Related but probably separate: variations on built previews. In email build output, the props panel is read-only ("rendered at build time"), so a deployed preview only ever shows one state of each template. The suggestion on #2339 of multiple named PreviewProps per template would fix that, because a finite set of variants can be pre-rendered at build time. That fits #2339 or #3716 better than this thread, so I'll pick it up there unless people would rather keep it together.

Things I'd want to agree on before writing code

• Are template statics the right home, and are PreviewSources / PreviewTransform the right names?
• (A), (B) or (C) above.
• Should PreviewTransform also feed the HTML tab, or only the iframe? I lean towards the iframe only, so the HTML tab stays an honest view of render().
• Should sources be able to opt out of email build, for expensive ones?

On contributing: happy to implement whichever version comes out of this thread.