Version 3

[IanEdington]

What would you like to see us solve for a version 3 of mjml-react?

We have a pretty good plan for how to generate typescript mjml-react components from the mjml src. A wish list from the community would be awesome!

So far:

1. Convert to TS (top request)
2. Clean up dependencies (highest cause of bugs so far)
3. Generate components from mjml src (what @Faire is doing internally)
4. Generate docs from mjml src or documentation.mjml.io
5. your suggestion!

Milestone containing what we aspire to accomplish in v3: https://github.com/Faire/mjml-react/milestone/1

We are developing version 3 on this branch: https://github.com/Faire/mjml-react/tree/main-v3

[IanEdington]

@iduuck Any feedback or suggestions you have are greatly appreciated

[iduuck]

I have already finished half the tasks for "my" mjml-react package. I would be willing to just take my work as a starting point for the typescript integration, and then switch out @postbote/mjml-react with your new implementation.

Also for convenience, I introduced a createMjmlElement function, which is taking care of the transformation.

[iduuck]

Also, I would suggest, that we are encapsulating the render method from the mjml-react package, because it is just a "pre-configured" version of the mjml-core function mjml2html. However, there will also be use for frontend usage, where mjml-browser could come in handy (like in my case with postbote).

[IanEdington]

I'm really digging the types you've come up with for % em ect. very nice! We're working on cleaning up our internal mjml-react and it would be great if we could merge the two.

I would suggest, that we are encapsulating the render method from the mjml-react package

Yeah, I like that idea. Are you thinking of pulling it out of index.js into its own file that can be imported independently? That would allow users to skip importing uglify-js when developing in the browser.

[iduuck]

Yeah, either into it's own package, and we are rewriting the repository into a monorepo (as I did) or we are going to have a separate file (but this should be done properly then, so that we are able to do tree-shaking.

[IanEdington]

Hi @iduuck, We've added our generated mjml components to the main-v3 branch and would appreciate any PR's you're willing to work on. I'm especially interested in the work you did on types but anything else you've got that you think would be worth adding would be awesome too! 🙏

[IanEdington]

Mono-repo with multiple packages vs package with core functionality + extra files.
@pruhstal @iduuck I figured I would break this conversation out into it's own thread

[IanEdington]

I'm definitely partial to having a single package to start with. My strategy would be to keep the index.ts file pretty slim and split out functionality into separate files.

• Developer 1 can import directly from those files for that extra functionality (and install required packages)
• Developer 2 wouldn't have to have it bundled in their application

This seems like the easiest way to get code-splitting without the overhead of a multi-repo.

If this package grows quite a bit I could see moving to a multi-repo in the future but I don't see the value right now.

happy to take feedback on this viewpoint

[Bertg]

Storybook support

today we are running a micro service with typescript, ts-node, nodemailer, handlebars and mjml. We made this work by modifying Module._load to use mjml() when appropriate. And this works great.

We also set this up with Storybook by modifying its webpack config (adding a loader to config.module.rules). And this also works great.

We would like to switch to this project, but we do want to keep our Storybook. However, I have not been able to get it working. It would be great if there was some example on how to get that to work.

[IanEdington]

Great suggestion! We use storybook extensively and if @faire/mjml-react goes well and is well received we're hoping to release some more comprehensive storybook tooling.

Are you currently writing emails in .mjml or in mjml-react?
If it's mjml-react it should be a pretty straightforward replacement (please file an issue if it's not working).

If you're using .mjml files you'll need a storybook decorator.

This is what we use. It's not complete but should give you an idea where to start from. Hope it helps

/**
 * Decorator to render emails from mjml-react to html
 * By using a Decorator our code snippets are cleaner and we ensure all stories render the same way.
 *
 * globals.generatedHtml - provides the html generated from mjml as a global so other tools can use it
 */
export const renderEmailDecorator: DecoratorFn = (storyFn, context) => {
  const params = context.parameters;
  const renderingOptions: Options = params.component?.renderingOptions ?? {};
  const [globalState, updateGlobals] = useGlobals();

  let html: string | undefined;
  let mjml: string | undefined;
  let error: MjmlError | undefined;
  try {
    const result = renderEmailToHTML(storyFn(context), renderingOptions);
    html = result.html;
    mjml = result.mjml;
  } catch (e) {
    error = e;
    mjml = error?.mjml;
    html = error?.mjmlHtml;
  }

  React.useEffect(() => {
    const typedGlobalState = globalState as RenderGlobals;
    if (
      context.viewMode === "story" &&
      (typedGlobalState.generatedHtml?.[context.id] !== html ||
        typedGlobalState.generatedMjml?.[context.id] !== mjml ||
        (!!error && !isEqual(typedGlobalState.mjmlErrors?.[context.id], error)))
    ) {
      const globals: RenderGlobals = {
        generatedHtml: { [context.id]: html },
        generatedMjml: { [context.id]: mjml },
        mjmlErrors: { [context.id]: error },
      };
      // This causes a re-render which is why this check is here
      // Currently this is overriding the state with a new object with a single story html. This is intentional since
      // there should never be more than one at a time since it's only being used in story view.
      updateGlobals(globals);
    }
  }, [globalState]);

  if (error) {
    return (
      <>
        <ErrorBox>
          An error occurred. See the Debug panels for more info.
          <pre>{error.message}</pre>
          <details>
            <code>{error.stack}</code>
          </details>
        </ErrorBox>
        <Spacer size="2x" />
        {html ? (
          <>
            <Typography variant="displaySSerifRegular">
              Rendering of Broken HTML
            </Typography>
            <Spacer size="2x" />
            <div dangerouslySetInnerHTML={{ __html: html }} />
          </>
        ) : null}
      </>
    );
  }

  return html ? (
    <div dangerouslySetInnerHTML={{ __html: html }} />
  ) : (
    <Typography>No Available HTML</Typography>
  );
};

[telam]

Great suggestion! We use storybook extensively and if @faire/mjml-react goes well and is well received we're hoping to release some more comprehensive storybook tooling.

Are you currently writing emails in .mjml or in mjml-react?
If it's mjml-react it should be a pretty straightforward replacement (please file an issue if it's not working).

If you're using .mjml files you'll need a storybook decorator.

This is what we use. It's not complete but should give you an idea where to start from. Hope it helps

/**
 * Decorator to render emails from mjml-react to html
 * By using a Decorator our code snippets are cleaner and we ensure all stories render the same way.
 *
 * globals.generatedHtml - provides the html generated from mjml as a global so other tools can use it
 */
export const renderEmailDecorator: DecoratorFn = (storyFn, context) => {
  const params = context.parameters;
  const renderingOptions: Options = params.component?.renderingOptions ?? {};
  const [globalState, updateGlobals] = useGlobals();

  let html: string | undefined;
  let mjml: string | undefined;
  let error: MjmlError | undefined;
  try {
    const result = renderEmailToHTML(storyFn(context), renderingOptions);
    html = result.html;
    mjml = result.mjml;
  } catch (e) {
    error = e;
    mjml = error?.mjml;
    html = error?.mjmlHtml;
  }

  React.useEffect(() => {
    const typedGlobalState = globalState as RenderGlobals;
    if (
      context.viewMode === "story" &&
      (typedGlobalState.generatedHtml?.[context.id] !== html ||
        typedGlobalState.generatedMjml?.[context.id] !== mjml ||
        (!!error && !isEqual(typedGlobalState.mjmlErrors?.[context.id], error)))
    ) {
      const globals: RenderGlobals = {
        generatedHtml: { [context.id]: html },
        generatedMjml: { [context.id]: mjml },
        mjmlErrors: { [context.id]: error },
      };
      // This causes a re-render which is why this check is here
      // Currently this is overriding the state with a new object with a single story html. This is intentional since
      // there should never be more than one at a time since it's only being used in story view.
      updateGlobals(globals);
    }
  }, [globalState]);

  if (error) {
    return (
      <>
        <ErrorBox>
          An error occurred. See the Debug panels for more info.
          <pre>{error.message}</pre>
          <details>
            <code>{error.stack}</code>
          </details>
        </ErrorBox>
        <Spacer size="2x" />
        {html ? (
          <>
            <Typography variant="displaySSerifRegular">
              Rendering of Broken HTML
            </Typography>
            <Spacer size="2x" />
            <div dangerouslySetInnerHTML={{ __html: html }} />
          </>
        ) : null}
      </>
    );
  }

  return html ? (
    <div dangerouslySetInnerHTML={{ __html: html }} />
  ) : (
    <Typography>No Available HTML</Typography>
  );
};

@IanEdington are you aware of any issues with Storybook 8 + Vite + Typescript? I have something very similar to what you suggested and I can see Vite's HMR working properly but Storybook isn't re-rendering the component. I've stepped through their code and saw they used the react-refresh library underneath. Is the useEffect() in your code above necessary for the HMR to work properly? I've tested other non-MJML components in Storybook and they are refreshing properly.

Edit: replaced useHook() with useEffect()

[IanEdington]

Unfortunately, I won't be much help with Vite, this is the first time I've heard of it.

I don't see a useHook in the code above.
The useGlobals is there to provide the output html, mjml, and error to other plugins. It isn't necessary for rendering
useEffect is there to avoid re-renders from setting globals.

You could trim it down to

/**
 * Decorator to render emails from mjml-react to html
 * By using a Decorator our code snippets are cleaner and we ensure all stories render the same way.
 *
 * globals.generatedHtml - provides the html generated from mjml as a global so other tools can use it
 */
export const renderEmailDecorator: DecoratorFn = (storyFn, context) => {
  const params = context.parameters;
  const renderingOptions: Options = params.component?.renderingOptions ?? {};

  let html: string | undefined;
  let mjml: string | undefined;
  let error: MjmlError | undefined;
  try {
    const result = renderEmailToHTML(storyFn(context), renderingOptions);
    html = result.html;
    mjml = result.mjml;
  } catch (e) {
    error = e;
    mjml = error?.mjml;
    html = error?.mjmlHtml;
  }

  if (error) {
    return (
      <>
        <ErrorBox>
          An error occurred. See the Debug panels for more info.
          <pre>{error.message}</pre>
          <details>
            <code>{error.stack}</code>
          </details>
        </ErrorBox>
        <Spacer size="2x" />
        {html ? (
          <>
            <p>
              Rendering of Broken HTML
            </p>
            <Spacer size="2x" />
            <div dangerouslySetInnerHTML={{ __html: html }} />
          </>
        ) : null}
      </>
    );
  }

  return html ? (
    <div dangerouslySetInnerHTML={{ __html: html }} />
  ) : (
    <div>No Available HTML</div>
  );
};

[telam]

@IanEdington apologies for the useHook confusion I was typing on my phone and didn't catch my typo. Thank you for the explanation of the useEffect(). I'm still relatively new to Storybook. At first, I assumed you were invaliding a global cache or something to get Storybook to re-render the component properly. My issue is strange. I have essentially the same decorator with even less code:

import type { Preview } from "@storybook/react";
import mjml2html from "mjml-browser";
import { renderToMjml } from "@faire/mjml-react/utils/renderToMjml";

const preview: Preview = {
  ... // other config
  decorators: [
    (Story) => {
      const mjml = renderToMjml(<Story />);
      const { html } = mjml2html(mjml, { validationLevel: "soft" });
      return (
        <div dangerouslySetInnerHTML={{ __html: html }} />
      );
    },
  ],
}

My component renders the first time, but when I make changes to the main component file nothing updates in Storybook. I see a log from vite that says [vite] hot updated: /src/templates/Example/Example.tsx but nothing changes in Storybook.

[telam]

@IanEdington here is a reproduction of my issue: https://stackblitz.com/edit/github-tgehw4?file=src%2Fstories%2FExample.tsx