Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Faire/mjml-react
React component library to generate the HTML emails on the fly
https://github.com/Faire/mjml-react
Last synced: about 1 month ago
JSON representation
React component library to generate the HTML emails on the fly
- Host: GitHub
- URL: https://github.com/Faire/mjml-react
- Owner: Faire
- License: mit
- Created: 2022-09-08T00:56:35.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-27T18:38:47.000Z (3 months ago)
- Last Synced: 2024-10-30T00:33:59.442Z (about 1 month ago)
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@faire/mjml-react
- Size: 584 KB
- Stars: 388
- Watchers: 19
- Forks: 17
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.MD
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- my-awesome-list - mjml-react
README
[Jump to getting started](#getting-started)
## Announcement from Engineering @ Faire
Hello mjml community, we at Faire are excited to announce we will be taking over maintaining the open-source mjml-react project!
Over the past year, Faire has used mjml-react extensively. This package allowed us to incorporate all the benefits of mjml without having to ask our developers to learn a new dev environment when moving from web to email. As a result, we significantly reduced the development effort for creating emails, while keeping email rendering issues to a minimum.
We saw so much benefit from mjml-react, and we don’t want to see it go. That is why we want to continue to maintain the package, and improve it with some of our own new ideas! For now you can check us out at [@faire/mjml-react](https://github.com/Faire/mjml-react). We hope this can be a drop-in replacement for mjml-react in most cases, but are eager to work with you if there are any issues. Don’t hesitate to reach out to us on the #mjml-react channel in the [MJML Slack Group](https://join.slack.com/t/mjml/shared_invite/zt-gqmwfwmr-kPBnfuuB7wof5httaTcXxg) or file a [github issue](https://github.com/Faire/mjml-react/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc). From there, you can look forward to new improvements coming soon.
And of course we want to extend a massive thank you to the Wix team for building and previously maintaining this project.
# mjml-react · [](https://github.com/faire/mjml-react/blob/master/LICENSE) 
[](https://github.com/faire/mjml-react/pulls)
· ![]()
There is an awesome library [mjml](https://mjml.io/) with github repo here [https://github.com/mjmlio/mjml](https://github.com/mjmlio/mjml).
`MJML` is a markup language created by [Mailjet](https://www.mailjet.com/).
So in order to create emails on the fly we created a library with `React` components.
## Get started today with V2 - 100% backwards compatible with https://github.com/wix-incubator/mjml-react/
V2 is a drop in replacement for https://github.com/wix-incubator/mjml-react/, with some additional support. If there's a component missing you can make a PR against https://github.com/Faire/mjml-react/tree/main-v2 or submit an issue and we'll try to unblock you.
## What's new in V3?
We wanted V3 of mjml-react to be fairly easy to migrate to from V2. We will implement more advanced features in V4. The main updates in V3 include:
- Typescript: mjml-react is now written in typescript which helps ensure correct props are passed to mjml components
- Full mjml component support: We use an automated script for pulling mjml components and creating a corresponding mjml-react component. This means we get full support of all components available in the latest mjml version
- Other small changes: add dangerouslySetInnerHTML in mjml-react for mjml ending tags, update testing, add in-code documenation
## What's coming in V4?
In V4 we are exploring exciting features that will make mjml-react even more powerful. This includes:
- Improved prop type safety: help ensure correct formatting for props like padding, width, and height
If you want to be on the cutting edge of what is being released, we are publishing a [v4-main-alpha version](https://www.npmjs.com/package/@faire/mjml-react/v/main-alpha) to npm.
## Getting Started
1. Choose between rendering in mjml or mjml-browser based on your rendering environment. Also includes additional required dependencies.
node:
```bash
npm install @faire/mjml-react mjml react react-dom
```
browser:
```bash
npm install @faire/mjml-react mjml-browser react react-dom
```
2. Wire up your render function (uncomment `mjml` or `mjml-browser`)
```tsx
import { renderToMjml } from "@faire/mjml-react/utils/renderToMjml";
// import mjml2html from "mjml";
// import mjml2html from "mjml-browser";
import { MJMLParseResults } from "mjml-core";
import React from "react";
export function renderReactToMjml(email: React.ReactElement): MJMLParseResults {
return mjml2html(renderToMjml(email));
}
```
3. And afterwards write a code like a pro:
```tsx
import {
Mjml,
MjmlHead,
MjmlTitle,
MjmlPreview,
MjmlBody,
MjmlSection,
MjmlColumn,
MjmlButton,
MjmlImage,
} from "@faire/mjml-react";
import { renderReactToMjml } from "./renderReactToMjml";
const { html, errors } = renderReactToMjml(
Last Minute Offer
Last Minute Offer...
I like it!
,
{ validationLevel: "soft" }
);
```
And as the result you will get a nice looking email HTML (works in mobile too!)
## Options
@faire/mjml-react sets the following MJML options when rendering to HTML:
```js
{
keepComments: false,
beautify: false,
minify: true,
validationLevel: 'strict'
}
```
If you want to override these, you can pass an object to `render` as a second argument. See the [MJML docs](https://documentation.mjml.io/#inside-node-js) for the full list of options you can set.
## Extensions
```js
import {
MjmlHtml,
MjmlComment,
MjmlConditionalComment
} from '@faire/mjml-react/extensions';
Built with ... at ...
//
MSO conditionals
//
MSO conditionals
//
//
Hello World!
```
## Utils
We do have also some utils for post processing the output HTML.
Because not all mail clients do support named HTML entities, like `'`.
So we need to replace them to hex.
```js
import {
namedEntityToHexCode,
fixConditionalComment,
} from "@faire/mjml-react/utils";
const html = "
'";
namedEntityToHexCode(html);
// '
fixConditionalComment(
"",
"Hello",
"if IE"
);
//
```
## Limitations
Currently `mjml` and `@faire/mjml-react` libraries are meant to be run inside a node.
## Example project
You can find an example project here
[https://github.com/wix-incubator/mjml-react-example](https://github.com/wix-incubator/mjml-react-example)