Guide

React Email : des modèles d'e-mails faits de composants

React Email transforme des templates JSX en HTML compris par les clients mail. Version 6.9.2, licence MIT, Tailwind, rendu, envoi via tout fournisseur.

L'équipe CodeWorlds18 min de lecture ·

Pratique HTML et CSS dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article9

React Email est un ensemble de composants React plus un outil en ligne de commande qui transforment un template JSX en HTML que les clients mail comprennent. Le paquet react-email est à la version 6.9.2, publiée le 7 août 2026, le dépôt resend/react-email compte environ 19,6 mille étoiles, et la licence est MIT sans variante payante.

Pourquoi le HTML d'e-mail obéit à d'autres règles

Une page web a un seul destinataire technique : le navigateur. Un e-mail en a une douzaine ou plus, et aucun n'est tenu de s'accorder avec les autres. Le même code arrive dans Gmail sur le web, Gmail dans une application mobile, Outlook sur Windows, Apple Mail, Thunderbird et une longue traîne de fournisseurs nationaux. Chacun décide seul de la part de votre CSS qui passe.

Les conséquences sont concrètes. Une feuille de styles liée depuis une adresse externe est exclue, car un client mail ne la récupérera pas. JavaScript est exclu entièrement. Les règles écrites dans une balise <style> fonctionnent de façon inégale, ce que la documentation du composant Tailwind énonce clairement en renvoyant vers la base caniemail.com et son tableau de prise en charge pour cette fonction. Les variables CSS sont mal prises en charge. Même la notation des couleurs compte : la forme rgb(255 255 255 / 1) avec des espaces, que le Tailwind moderne utilise, n'est pas largement gérée, et la forme sûre est rgb(255,255,255) avec des virgules.

Comme on ne peut pas compter sur une feuille de styles, les styles vont dans l'attribut style de chaque élément. Comme on ne peut pas compter sur flex ou grid, la mise en page se décrit avec des tableaux imbriqués. C'est ainsi que se présentaient les templates d'e-mail écrits à la main depuis vingt ans, et c'est encore à quoi ressemble ce qui est remis au destinataire.

React Email ne change pas ces règles, car elles ne peuvent pas être changées. Il ne fait que déplacer l'endroit où l'on travaille. Vous écrivez des composants, et la couche de rendu produit des tableaux et des styles en attributs. Le confirmer prend un instant : décompressez @react-email/section, @react-email/row et @react-email/container, et le code compilé contient un élément table littéral. Ce ne sont pas des noms sémantiques qui habillent autre chose, ce sont des générateurs de tableaux.

Il y a une exception à la règle des styles en attributs. Les media queries, c'est-à-dire @media, ne peuvent pas s'écrire dans un attribut style, donc elles doivent atterrir dans une balise <style> à l'intérieur de <head>. La documentation du composant Tailwind décrit cela comme un compromis délibéré, avec une seconde décision : les noms de classes dans cette balise sont assainis pour éviter les caractères qui demandent des échappements par barre oblique inverse, car ceux-ci peuvent casser pas mal de clients.

Version, licence et composition des paquets

Distinguer trois paquets évite beaucoup de confusion à la première installation.

Le premier est react-email en version 6.9.2, publié le 7 août 2026. C'est l'outil en ligne de commande, qui expose la commande email. À l'intérieur se trouvent esbuild, chokidar, socket.io, commander, tailwindcss plus @babel/parser et @babel/traverse, tout le kit nécessaire à un serveur de prévisualisation avec rechargement en direct. Une curiosité du code de démarrage : l'exécutable vérifie si le processus Node a reçu les drapeaux --experimental-vm-modules et --disable-warning=ExperimentalWarning, et sinon se relance avec eux. Vous n'avez jamais à vous souvenir de ces drapeaux, mais si vous encapsulez cela dans un script, vous savez maintenant d'où vient le processus enfant supplémentaire.

Le deuxième est @react-email/components en version 1.0.12, le paquet agrégé. Il ne rend rien par lui-même et se contente de tirer vingt paquets distincts : body, button, code-block, code-inline, column, container, font, head, heading, hr, html, img, link, markdown, preview, render, row, section, tailwind et text. Chacun porte son propre numéro de version et son propre rythme de publication.

Le troisième est @react-email/render, à la fois dépendance des deux précédents et paquet autonome. La version actuelle dans le registre est la 2.1.0, tandis que @react-email/components 1.0.12 épingle en interne la 2.0.6. Si vous auditez les versions de dépendances dans votre projet, cet écart est normal et découle du fait que le paquet agrégé épingle les versions exactes au moment de sa propre publication.

La licence est sans ambiguïté, ce qui est assez rare pour être noté. Le fichier LICENSE.md à la racine du dépôt porte le texte MIT complet avec la mention « Copyright 2024 Plus Five Five, Inc ». Le champ license du registre npm pour react-email, pour @react-email/components et pour les paquets de composants indique MIT. L'interface programmatique de GitHub indique MIT License pour le dépôt avec l'identifiant SPDX MIT. Il n'y a aucun répertoire qui contienne une licence commerciale séparée, aucun choix double, aucun module complémentaire dont l'installation tire un paquet propriétaire. Toute la fonctionnalité vit dans la version ouverte.

Santé du projet : 19638 étoiles, 1076 forks, 31 tickets ouverts, dernière modification sur la branche principale datée du 19 août 2026, dépôt créé en septembre 2022 et non archivé. Les exigences d'environnement sont légères, puisque les dépendances peer acceptent React 18 ou 19 avec un react-dom correspondant.

Installation et prévisualisation locale

Entrer dans un projet existant ressemble à ceci.

Bash
# the command line tool and the components
npm install --save-dev react-email
npm install @react-email/components

# preview server, defaults to ./emails and port 3000
npx email dev

# custom directory and port
npx email dev --dir ./src/emails --port 3001

# compatibility warnings for selected clients
npx email dev --clients gmail,outlook,protonmail

# write HTML files into the out directory
npx email export --outDir out --pretty

# plain text output instead of HTML
npx email export --plainText

# custom extension on the output files
npx email export --dir ./src/emails --extension blade.php

# a new project from scratch
npx create-email@latest

La commande email dev lance une application de prévisualisation dans le navigateur qui liste les templates du répertoire et les recharge à l'enregistrement. L'option --clients prend une liste séparée par des virgules et active les avertissements de compatibilité. Les valeurs acceptées sont gmail, outlook, yahoo, apple-mail, aol, thunderbird, microsoft, samsung-email, sfr, orange, protonmail, hey, mail-ru, fastmail, laposte, t-online-de, free-fr, gmx, web-de, ionos-1and1, rainloop et wp-pl, soit vingt-deux entrées dont le polonais wp-pl. La même liste peut être fournie par la variable d'environnement COMPATIBILITY_EMAIL_CLIENTS, que l'option remplace.

Les commandes email build et email start construisent et lancent l'application de prévisualisation elle-même, que l'outil copie dans un répertoire .react-email. Elles servent quand vous voulez exposer les prévisualisations de templates à une équipe marketing à une adresse fixe plutôt que de demander aux gens de lancer un serveur en local.

Celle qui compte le plus est email export. Elle prend les templates d'un répertoire et écrit le résultat sous forme de fichiers. L'option --extension permet de leur donner l'extension que vous voulez, et la documentation de la commande propose blade.php en exemple. Pour juger de la dépendance vis-à-vis du fournisseur, c'est le détail qui tranche : le produit de React Email est un fichier texte brut que l'on peut remettre à n'importe quel système, y compris un moteur de templates écrit dans un autre langage.

Un paquet publié séparément, create-email en version 1.2.5, génère un nouveau projet avec des templates d'exemple. Il a trois dépendances et revient à copier un répertoire de démarrage.

Anatomie d'un template

Voici un template de bienvenue qui utilise des composants dont j'ai vérifié les noms de champs dans les déclarations de types publiées.

TypeScript
import {
  Body, Button, Column, Container, Font, Head, Heading,
  Hr, Html, Img, Link, Preview, Row, Section, Text
} from '@react-email/components'

interface WelcomeEmailProps {
  userName: string
  activationUrl: string
}

export default function WelcomeEmail({ userName, activationUrl }: WelcomeEmailProps) {
  return (
    <Html lang="en" dir="ltr">
      <Head>
        <Font
          fontFamily="Inter"
          fallbackFontFamily={['Helvetica', 'Arial', 'sans-serif']}
          webFont={{
            url: 'https://example.com/fonts/inter-regular.woff2',
            format: 'woff2'
          }}
          fontWeight={400}
          fontStyle="normal"
        />
      </Head>
      <Preview>Confirm your address and start using your account</Preview>
      <Body style={{ backgroundColor: '#f4f4f5', margin: 0, padding: '24px 0' }}>
        <Container style={{ backgroundColor: '#ffffff', padding: '32px', maxWidth: '600px' }}>
          <Img
            src="https://example.com/logo.png"
            alt="Company logo"
            width="120"
            height="32"
          />
          <Heading as="h1" mt={24} mb={8} style={{ fontSize: '24px' }}>
            Hi {userName}
          </Heading>
          <Text style={{ fontSize: '16px', lineHeight: '24px', color: '#3f3f46' }}>
            One click left. Confirm your address to activate the account.
          </Text>
          <Section style={{ marginTop: '24px' }}>
            <Button
              href={activationUrl}
              style={{
                backgroundColor: '#2563eb',
                color: '#ffffff',
                padding: '12px 20px',
                borderRadius: '6px',
                msoPaddingAlt: '0px'
              }}
            >
              Activate account
            </Button>
          </Section>
          <Hr style={{ borderColor: '#e4e4e7', margin: '32px 0' }} />
          <Row>
            <Column>
              <Text style={{ fontSize: '12px', color: '#71717a' }}>
                Did not sign up? Ignore this message.
              </Text>
            </Column>
            <Column align="right">
              <Link href="https://example.com/help" style={{ fontSize: '12px' }}>
                Help
              </Link>
            </Column>
          </Row>
        </Container>
      </Body>
    </Html>
  )
}

Plusieurs détails de ce fichier méritent un commentaire. Font doit se trouver dans Head, exige les champs fontFamily et fallbackFontFamily, et son webFont prend un objet avec une URL et un format choisi parmi woff, woff2, truetype, opentype, embedded-opentype et svg. Les valeurs de repli viennent d'un ensemble fermé de polices système, et l'ordre du tableau est l'ordre de priorité. La déclaration de type elle-même avertit que tous les clients ne prennent pas en charge les polices web et renvoie vers la base de compatibilité.

Preview n'accepte que du texte, car il génère un fragment caché que les clients mail affichent à côté de l'objet dans la liste des messages. Sans lui, vous obtenez à cet endroit les premiers mots du corps, souvent une adresse d'image ou une formule de salutation qui n'apporte aucune information.

Heading a un champ as qui accepte h1 à h6 plus des champs de marges dédiés m, mx, my, mt, mr, mb et ml. Button est une ancre ordinaire et prend tous les attributs d'un élément a, y compris href et target. Ce paquet ajoute aussi deux champs propres au type React.CSSProperties, msoPaddingAlt et msoTextRaise, et c'est le point où les particularités des clients mail apparaissent directement dans l'interface de programmation.

Tailwind CSS dans un e-mail

Le composant Tailwind de @react-email/tailwind permet d'écrire des classes au lieu d'objets de style. La version actuelle est la 2.0.7 et elle dépend de tailwindcss en 4.1.18 ou plus récent, c'est-à-dire de la quatrième série de Tailwind CSS.

TypeScript
import { Button, Container, Section, Tailwind, Text } from '@react-email/components'

export default function OfferEmail({ discountCode }: { discountCode: string }) {
  return (
    <Tailwind
      config={{
        theme: {
          extend: {
            colors: {
              brand: '#2563eb',
              muted: '#71717a'
            }
          }
        }
      }}
    >
      <Container className="mx-auto max-w-[600px] bg-white p-8">
        <Section>
          <Text className="text-[18px] font-semibold text-brand">
            Discount code: {discountCode}
          </Text>
          <Text className="text-[14px] text-muted">
            The code is valid until the end of the month.
          </Text>
          <Button
            href="https://example.com/shop"
            className="rounded-md bg-brand px-5 py-3 text-white"
          >
            Go to the shop
          </Button>
        </Section>
      </Container>
    </Tailwind>
  )
}

Le champ config prend une configuration Tailwind privée de la clé content, visible dans la déclaration de type sous la forme Omit<Config, 'content'>. La clé content a disparu parce qu'il n'y a pas d'analyse de fichiers ici : le composant voit l'arbre React qu'il enveloppe, et c'est tout ce dont il a besoin.

Le mécanisme est décrit dans le readme du paquet et vaut la peine d'être connu avant que le résultat ne vous surprenne. Les classes sont transformées en styles écrits dans l'attribut style des éléments rendus plutôt que dans une feuille de styles partagée. Les media queries, qui ne peuvent pas être insérées ainsi, atterrissent dans une balise <style> à l'intérieur de <head> avec leurs noms de classes associés, et ces noms sont assainis. Les variables CSS, sur lesquelles la quatrième série de Tailwind appuie une grande partie de sa configuration, sont résolues par un plugin PostCSS dédié, et celles qu'il ne sait pas résoudre sont laissées telles quelles. Les couleurs écrites avec la syntaxe à espaces sont réécrites avec des virgules, et l'opacité donnée après une barre oblique devient le quatrième argument de la fonction rgb.

La conclusion pratique est qu'une partie de ce que Tailwind propose passe proprement et qu'une partie disparaît silencieusement. Les espacements, les couleurs, les tailles de texte et les coins arrondis correspondent à des propriétés simples et fonctionnent. Tout ce qui repose sur flex, grid ou le positionnement appelle à la prudence, car la classe sera générée, le style atteindra l'attribut, et le client mail pourra tout de même l'ignorer. Continuez à construire la mise en page avec Section, Row et Column, et traitez Tailwind comme une façon plus commode d'écrire des valeurs plutôt que comme une façon de décrire une grille.

Rendu et envoi via n'importe quel fournisseur

Tout le contact entre le template et le monde extérieur passe par une seule fonction.

TypeScript
import { render } from '@react-email/render'
import nodemailer from 'nodemailer'
import WelcomeEmail from './emails/welcome'

const element = WelcomeEmail({
  userName: 'Anna',
  activationUrl: 'https://example.com/activate?token=abc'
})

const html = await render(element, { pretty: true })
const text = await render(element, {
  plainText: true,
  htmlToTextOptions: { wordwrap: 80 }
})

const transporter = nodemailer.createTransport({
  host: 'smtp.example.com',
  port: 587,
  auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS }
})

await transporter.sendMail({
  from: 'welcome@example.com',
  to: 'anna@example.com',
  subject: 'Confirm your address',
  html,
  text
})

La fonction render renvoie une promesse qui se résout en chaîne de caractères. Le jeu d'options est court et découle entièrement de la déclaration de type Options : pretty formate la sortie avec Prettier, plainText bascule la sortie en texte, htmlToTextOptions transmet des réglages directement à la bibliothèque html-to-text, et unstableTextConversion active un convertisseur de texte maison à la place de cette bibliothèque, auquel cas htmlToTextOptions n'est plus disponible. Le préfixe unstable dans le nom est un avertissement, pas une décoration.

On arrive ainsi à la question qui suscite le plus de doutes. Le projet est né chez Resend et appartient à la même entreprise, comme le montre la mention de licence, mais il ne crée aucune attache d'exécution. Le produit de render est une chaîne de HTML. Vous remettez cette chaîne à n'importe quel client SMTP ou à l'interface HTTP de n'importe quel fournisseur comme champ html. Cela fonctionne avec Resend, avec Postmark, avec Loops, avec votre propre serveur de messagerie et avec tout ce qui accepte du HTML.

Le seul endroit où Resend apparaît dans l'outil lui-même est la paire de commandes email resend setup et email resend reset. La première stocke une clé d'interface programmatique dans la configuration de l'outil, la seconde la supprime. Elle sert à envoyer des messages de test depuis la prévisualisation. Elle est entièrement optionnelle, et sans lancer ces commandes, l'outil ne contacte nulle part.

Le périmètre de responsabilité est un sujet à part. React Email n'envoie pas de messages, ne tient pas de listes de destinataires, ne gère pas les désabonnements, ne collecte pas de statistiques d'ouverture et ne gère pas la réputation du domaine expéditeur. Il ne remplace pas non plus l'authentification SPF, DKIM et DMARC. C'est une couche de templates, pas une plateforme de messagerie, et les confondre mène à la déception. Le rendu côté serveur dans Next.js ou dans n'importe quel environnement Node est à votre charge, à l'endroit où vous appelez de toute façon le fournisseur.

React Email face aux alternatives

CritèreReact EmailMJMLMaizzlejsx-emailHTML écrit à la main
Langage de templateJSX et composants Reactses propres balises XMLHTML avec des classes utilitairesJSX et composants ReactHTML écrit directement
Modèle d'exécutionReact rendu en HTMLbalisage compilé en HTMLcompilation avec inlining du CSSReact rendu en HTMLpas d'étape de build
Intégration de Tailwind CSSComposant Tailwind, série 4en dehors du cœurintégré, au cœur de l'outildisponible en complémentsans objet
Version actuelle6.9.25.4.06.1.03.2.1sans objet
LicenceMITMITMITMITsans objet

Le choix revient à une question : votre équipe écrit-elle du React de toute façon. Si oui, React Email permet de garder les templates dans le même dépôt, dans le même langage et sous la même vérification de types que le reste de l'interface. Les propriétés d'un template sont une interface TypeScript ordinaire, donc renommer un champ dans vos données casse la compilation au lieu de casser le message dans la boîte de réception de quelqu'un.

Si les templates sont écrits par quelqu'un qui ne connaît pas React, l'arithmétique est différente. MJML a une syntaxe plus simple et n'exige pas d'environnement Node pour le travail quotidien sur le contenu. Maizzle est un bon choix quand le point de départ est du HTML déjà prêt et que le travail consiste surtout à inliner commodément les styles. Écrire les tableaux à la main reste sensé pour un seul template transactionnel que personne n'a touché depuis deux ans, car chaque outil est une dépendance de plus à tenir à jour.

Erreurs courantes

La première est d'écrire un template comme on écrit une page. display: flex, position: absolute, les images de fond et les pseudo-éléments n'ont aucune garantie de fonctionner. La mise en page revient à Section, Row et Column, qui rendent des tableaux, et c'est la seule construction sur laquelle on peut compter partout.

La deuxième est de sauter la version texte brut. Certains destinataires et certains filtres ne voient que celle-là. Un second appel à render avec plainText: true et le passage du résultat comme champ text à l'envoi suffisent.

La troisième, ce sont les images sans dimensions et sans texte alternatif. De nombreux clients bloquent le chargement des images par défaut, donc le destinataire voit d'abord un cadre contenant le texte alt. La valeur de src doit être absolue et publiquement accessible, car un chemin relatif n'a rien à quoi se résoudre ici.

La quatrième est d'omettre le composant Preview. Sans lui, la liste des messages affiche le début du corps, qui est généralement une salutation ou le texte alternatif de la première image.

La cinquième est de s'appuyer sur des variables CSS dans la configuration Tailwind. Le plugin les résout avant le rendu, mais celles qu'il ne sait pas résoudre restent telles quelles dans la sortie, et un client mail n'en tirera rien de sensé.

La sixième est de confondre une prévisualisation dans un navigateur avec un test en boîte de réception. Le serveur email dev rend dans un navigateur, un environnement bien plus indulgent que la cible. L'option --clients produit des avertissements de compatibilité, mais la vérification finale reste l'envoi vers de vrais comptes.

La septième est d'installer react-email seul et d'y chercher des composants. Ce paquet contient l'outil en ligne de commande. Les composants vivent dans @react-email/components ou dans les paquets individuels et doivent être ajoutés séparément.

FAQ

React Email me lie-t-il à Resend ?

Pas techniquement. Le produit est une chaîne de HTML que vous remettez à n'importe quel fournisseur ou serveur SMTP. Les commandes email resend setup et email resend reset sont optionnelles et ne concernent que l'envoi de tests depuis la prévisualisation. Le lien est un lien de propriété, puisque le projet appartient à l'entreprise derrière Resend, et il vaut la peine d'en tenir compte pour juger de son orientation.

Ai-je besoin de React dans mon application pour utiliser React Email ?

Pas dans le front end de production, mais il faut React et react-dom comme dépendances dans l'environnement qui rend les messages. Les dépendances peer acceptent les versions 18 et 19. Vous pouvez aussi passer par email export et traiter React Email comme un générateur de fichiers HTML exécuté en dehors de l'application.

Tailwind fonctionne-t-il vraiment dans un e-mail ?

En partie, et c'est la réponse honnête. Les classes deviennent des styles dans l'attribut style, les media queries atterrissent dans une balise <style>, les couleurs sont réécrites dans une syntaxe que les clients gèrent, et les variables CSS sont résolues par un plugin PostCSS. Tout ce qui touche aux espacements, aux couleurs et à la typographie passe bien. Une mise en page qui repose sur flex ou grid reste risquée.

Comment générer la version texte brut ?

Avec un appel render(element, { plainText: true }). La conversion passe par défaut par la bibliothèque html-to-text, que vous pouvez régler via htmlToTextOptions. L'option unstableTextConversion bascule vers le convertisseur propre au projet, et le passage des réglages de cette bibliothèque n'est alors plus disponible.

La prévisualisation locale remplace-t-elle les tests dans les clients mail ?

Non. Le serveur email dev montre le template dans un navigateur, qui laisse passer bien plus que les logiciels de messagerie cibles. L'option --clients active des avertissements de compatibilité pour vingt-deux clients, dont wp-pl, mais cela reste de l'analyse statique plutôt qu'un vrai rendu.

React Email est-il payant ?

Non. Les paquets react-email et @react-email/components et chaque paquet de composants portent la licence MIT dans le registre npm, et le LICENSE.md du dépôt contient le texte MIT complet. Il n'y a ni variante commerciale, ni fonction derrière un supplément, ni plafond d'usage. Le service d'envoi coûte de l'argent si vous en choisissez un, mais c'est un produit distinct.

La documentation se trouve sur react.email, le code source dans le dépôt GitHub, et les tableaux de prise en charge de chaque propriété CSS dans la base caniemail.

À lire aussi