Cómo organizar componentes reutilizables en MJML

Cuando empiezas a maquetar emails con MJML, la primera sensación suele ser bastante agradable: todo parece más limpio que trabajar directamente con tablas HTML, las columnas son más fáciles de entender y la estructura general del email resulta menos intimidante. MJML está pensado precisamente para reducir la complejidad de crear emails responsive, usando una sintaxis más legible que después se transforma en HTML compatible con distintos clientes de correo.

Pero hay un punto en el que esa comodidad inicial puede empezar a desordenarse: cuando dejas de tener una sola newsletter puntual y pasas a mantener varias campañas, automatizaciones, emails transaccionales, cabeceras, footers, banners, bloques de producto, llamadas a la acción y versiones para distintos públicos.

Ahí aparece la gran pregunta: cómo organizar componentes reutilizables en MJML sin convertir el proyecto en una carpeta llena de archivos imposibles de mantener.

La respuesta no está solo en “separar archivos”. Está en pensar el email como un pequeño sistema de diseño: con piezas reutilizables, estilos globales, nombres claros, componentes con una responsabilidad concreta y una estructura que permita escalar sin duplicar código en cada campaña.

Si estás dando tus primeros pasos con esta tecnología, antes puede ayudarte leer qué es MJML y por qué facilita la maquetación de emails responsive. Y si ya vienes de trabajar con HTML tradicional, también te recomiendo revisar la comparación entre MJML vs HTML tradicional para emails, porque entender esas diferencias ayuda mucho a organizar mejor cualquier proyecto.

Por qué tiene sentido crear componentes reutilizables en MJML

Un email rara vez es una pieza completamente nueva desde cero. Aunque cambie el contenido, muchas partes suelen repetirse: el encabezado, el logo, el footer legal, los botones, los separadores, los módulos de imagen más texto, las tarjetas de producto, las llamadas a la acción o los bloques de artículos recomendados.

Si cada email copia y pega esos bloques manualmente, tarde o temprano aparecen problemas: cambios de marca aplicados en unos emails sí y en otros no, botones con paddings diferentes, footers legales desactualizados, errores visuales por duplicar estructuras complejas y mucho tiempo perdido revisando detalles que ya deberían estar resueltos.

Aquí es donde la reutilización aporta valor. Organizar componentes reutilizables en MJML permite convertir piezas repetidas en bloques consistentes, fáciles de mantener y más seguros para producción.

MJML ya trabaja con una lógica basada en componentes. Elementos como <mj-section>, <mj-column>, <mj-text>, <mj-image> o <mj-button> permiten construir emails a partir de bloques comprensibles. La clave está en dar un paso más: no usar solo los componentes base de MJML, sino crear una organización propia para que el proyecto tenga una lógica de sistema.

Esto cobra todavía más importancia cuando trabajas newsletters, campañas recurrentes o automatizaciones. En esos casos, no solo estás diseñando un email; estás creando una pequeña biblioteca de piezas que vas a reutilizar muchas veces.

Qué entendemos por componentes reutilizables en MJML

Cuando hablamos de componentes MJML reutilizables, no nos referimos necesariamente a componentes como los de React, Vue o Svelte. En MJML, la reutilización puede adoptar varias formas.

Puede ser un archivo parcial que se incluye en varias plantillas, una sección completa que se repite, un conjunto de estilos globales dentro de <mj-attributes>, una clase reutilizable con mj-class o incluso un bloque de contenido generado desde Node.js antes de compilar el MJML final.

Lo importante es que el componente tenga una función clara y pueda reutilizarse sin tener que reescribirlo cada vez.

<mj-section background-color="#F8E0EA" padding="32px 24px"> <mj-column> <mj-text font-size="24px" font-weight="700" color="#020101"> Título de la campaña </mj-text> <mj-text font-size="16px" line-height="1.6" color="#333333"> Texto introductorio del email. </mj-text> <mj-button background-color="#CC2B5E" color="#ffffff" border-radius="8px"> Leer más </mj-button> </mj-column>
</mj-section>

Este bloque podría ser un hero reutilizable. Pero si lo copiamos y pegamos en diez emails, no estamos reutilizando de verdad: solo estamos duplicando una estructura. Para que sea realmente reutilizable, lo ideal es aislarlo dentro de una arquitectura clara.

Una estructura de carpetas clara para proyectos MJML

La organización de carpetas es una de las decisiones más importantes. No hace falta complicarla demasiado, pero sí conviene separar las piezas según su responsabilidad.

Una estructura práctica podría ser esta:

emails/ templates/ newsletter.mjml welcome.mjml password-reset.mjml components/ header.mjml footer.mjml hero.mjml button-primary.mjml article-card.mjml product-card.mjml divider.mjml layouts/ base.mjml marketing-layout.mjml transactional-layout.mjml styles/ attributes.mjml fonts.mjml head.mjml data/ newsletter.json products.json dist/ newsletter.html welcome.html

Esta estructura separa varios niveles. Las templates son los emails finales, como una newsletter, un email de bienvenida o una recuperación de contraseña. Los components son piezas reutilizables pequeñas o medianas, como cabeceras, botones, tarjetas o bloques de contenido.

Los layouts definen estructuras generales. Por ejemplo, un layout de marketing con hero y CTA, o un layout transaccional más sobrio. Los archivos de styles agrupan configuración global, fuentes, clases, atributos y estilos comunes. Y la carpeta dist contiene el HTML final compilado, listo para probar o integrar en una herramienta de email marketing.

La ventaja de esta separación es que cada archivo tiene un papel claro. No mezclas el contenido de una campaña concreta con el estilo global de todos los emails, ni duplicas el footer en cada plantilla.

Cómo usar mj-include para dividir archivos

Una de las formas más directas de reutilizar piezas en MJML es usar <mj-include>. Este recurso permite incluir otros archivos dentro de una plantilla principal, lo que resulta muy útil para cabeceras, footers, bloques repetidos o estilos compartidos.

Por ejemplo, una plantilla principal podría verse así:

<mjml> <mj-head> <mj-include path="../styles/attributes.mjml" /> </mj-head> <mj-body background-color="#ffffff"> <mj-include path="../components/header.mjml" /> <mj-include path="../components/hero.mjml" /> <mj-include path="../components/article-card.mjml" /> <mj-include path="../components/footer.mjml" /> </mj-body>
</mjml>

Esto hace que el email final sea mucho más fácil de leer. En lugar de enfrentarte a un archivo enorme de cientos de líneas, puedes ver la composición general del email de un vistazo.

Cuándo usar archivos parciales

Los parciales funcionan muy bien cuando una pieza se repite en varios emails y no cambia demasiado. Por ejemplo: header corporativo, footer legal, bloque de redes sociales, separadores visuales, banner promocional, módulo de artículo destacado, CTA final o bloque de aviso legal.

La clave está en no crear parciales para absolutamente todo. Si fragmentas demasiado, puedes acabar con una arquitectura difícil de seguir. Un componente reutilizable debe tener una razón clara para existir.

Qué no conviene convertir en componente

No todo merece ser un componente. Si un bloque solo aparece una vez y no tiene previsión de repetirse, quizá sea mejor dejarlo dentro de la plantilla.

Tampoco conviene crear componentes demasiado específicos, como este:

hero-black-friday-2026-discount-30.mjml

Ese archivo difícilmente será reutilizable. En cambio, tendría más sentido crear algo como esto:

hero-campaign.mjml

Después puedes modificar el contenido desde la plantilla, desde variables o desde una fase previa de renderizado si trabajas con Node.js.

Centralizar estilos con mj-attributes y mj-class

Una parte esencial de los componentes reutilizables en MJML es evitar repetir estilos en cada bloque. Si todos los botones tienen el mismo color, border-radius, padding y tipografía, no tiene sentido escribir esos atributos una y otra vez.

MJML permite definir estilos globales dentro de <mj-head>, especialmente mediante <mj-attributes>. Esta técnica ayuda a establecer valores por defecto para componentes como <mj-text>, <mj-button> o <mj-section>.

<mj-attributes> <mj-text font-family="Arial, sans-serif" font-size="16px" line-height="1.6" color="#020101" /> <mj-button font-family="Arial, sans-serif" font-size="16px" font-weight="700" background-color="#CC2B5E" color="#ffffff" border-radius="8px" padding="16px 24px" /> <mj-section padding="24px" />
</mj-attributes>

Con esta configuración, cada vez que uses <mj-text> o <mj-button>, partirás de una base común. Después podrás sobrescribir atributos concretos si una pieza necesita un ajuste específico.

Esta idea conecta muy bien con otras decisiones de diseño y desarrollo frontend: crear una base común, reducir la repetición y mantener criterios consistentes. Es el mismo principio que aplicamos cuando organizamos estilos, componentes o patrones visuales en una web.

Crear variantes con mj-class

Además de estilos globales, puedes crear clases reutilizables con mj-class. Por ejemplo:

<mj-attributes> <mj-class name="text-muted" color="#666666" font-size="14px" line-height="1.5" /> <mj-class name="heading-lg" font-size="28px" font-weight="700" line-height="1.3" color="#020101" /> <mj-class name="button-secondary" background-color="#753A88" color="#ffffff" border-radius="8px" />
</mj-attributes>

Después puedes aplicarlas así:

<mj-text mj-class="heading-lg"> Novedades de la semana
</mj-text> <mj-text mj-class="text-muted"> Una selección breve de recursos para mejorar tus emails.
</mj-text> <mj-button mj-class="button-secondary"> Ver recursos
</mj-button>

Este enfoque se parece mucho a trabajar con tokens o utilidades de diseño. Ayuda a mantener consistencia sin llenar cada componente de atributos repetidos.

Consejo práctico para nombres de clases

Los nombres deben explicar intención, no apariencia temporal. Es mejor usar nombres como heading-lg, text-muted, button-primary o section-soft que nombres como text-gray, button-purple o pink-section.

¿Por qué? Porque la marca puede cambiar de color, pero la intención del componente se mantiene. Un botón primario seguirá siendo primario aunque mañana cambie de rosa a azul.

Diseñar componentes por responsabilidad, no por campaña

Uno de los errores más comunes al organizar reusable email components es pensar en campañas concretas en lugar de pensar en responsabilidades.

Por ejemplo, podrías tener un archivo llamado:

newsletter-january-header.mjml

Pero eso lo ata demasiado a una campaña concreta. En cambio, conviene pensar en algo más reutilizable:

header-brand.mjml

La pregunta útil es: qué hace este componente.

¿Presenta la marca? ¿Muestra una imagen destacada? ¿Agrupa un listado de artículos? ¿Cierra el email con información legal? ¿Guía hacia una acción principal? ¿Muestra una tarjeta de producto?

Si el nombre responde a la función, será más fácil reutilizarlo en distintos contextos.

Componentes pequeños, medianos y grandes

No todos los componentes tienen que tener el mismo tamaño. Puedes pensar en tres niveles.

Los componentes pequeños pueden ser botones, separadores, bloques de texto, badges o pequeños avisos. Los componentes medianos pueden ser tarjetas de artículo, bloques de producto, módulos de imagen más texto o llamadas a la acción. Y los componentes grandes pueden ser headers, footers, heroes, secciones completas o bloques de campaña.

Esta división ayuda a evitar dos extremos: componentes enormes que hacen demasiadas cosas o componentes tan pequeños que obligan a abrir veinte archivos para entender un email.

Ejemplo de sistema de componentes MJML para una newsletter

Imaginemos una newsletter mensual sobre desarrollo web. Podríamos definir las siguientes piezas:

components/ header-brand.mjml hero-newsletter.mjml intro-text.mjml article-card.mjml resource-list.mjml cta-block.mjml footer-legal.mjml

La plantilla final quedaría mucho más limpia:

<mjml> <mj-head> <mj-include path="../styles/head.mjml" /> <mj-include path="../styles/attributes.mjml" /> </mj-head> <mj-body background-color="#ffffff"> <mj-include path="../components/header-brand.mjml" /> <mj-include path="../components/hero-newsletter.mjml" /> <mj-include path="../components/intro-text.mjml" /> <mj-include path="../components/article-card.mjml" /> <mj-include path="../components/resource-list.mjml" /> <mj-include path="../components/cta-block.mjml" /> <mj-include path="../components/footer-legal.mjml" /> </mj-body>
</mjml>

Desde fuera, la plantilla cuenta una historia clara: cabecera, hero, introducción, contenido principal, recursos, CTA y cierre. Eso mejora mucho la mantenibilidad.

Si estás trabajando una primera newsletter desde cero, puedes ampliar esta parte con la guía sobre cómo crear tu primera newsletter responsive con MJML, donde la prioridad está más en la estructura inicial del email y no tanto en la arquitectura de componentes.

Separar estructura, contenido y presentación

Para proyectos pequeños, puedes mantener contenido y estructura juntos. Pero si vas a trabajar con muchas campañas, es mejor separar tres capas: estructura, contenido y presentación.

La estructura define qué bloques existen y en qué orden aparecen. El contenido incluye textos, enlaces, imágenes y datos variables. La presentación agrupa estilos globales, colores, tipografías, espaciados y clases.

Esta separación no tiene que ser perfecta desde el primer día. Pero cuanto más crece el proyecto, más se agradece.

Cómo trabajar con datos dinámicos y MJML

MJML puede integrarse en workflows con Node.js para generar HTML a partir de plantillas. Esto abre una posibilidad interesante: crear emails a partir de datos externos.

Por ejemplo, podrías tener un archivo JSON con el contenido de una newsletter:

{ "title": "Recursos de frontend de la semana", "intro": "Una selección breve para mejorar tus proyectos.", "articles": [ { "title": "Cómo mejorar la accesibilidad de tus formularios", "url": "https://example.com/articulo-1" }, { "title": "Buenas prácticas para emails responsive", "url": "https://example.com/articulo-2" } ]
}

Después, con un script de Node.js, podrías generar el MJML final antes de compilarlo a HTML. En ese caso, MJML funciona como capa de presentación, mientras que los datos vienen de otra fuente: un CMS, una API, un JSON o una base de datos.

Este enfoque es muy útil cuando necesitas producir muchas variaciones de un email sin cambiar manualmente cada archivo. También encaja bien con un workflow frontend moderno, donde el código, los datos y la generación de archivos pueden formar parte de un proceso automatizado.

Buenas prácticas para nombrar componentes MJML

La nomenclatura parece un detalle menor, pero en proyectos reales marca una gran diferencia. Un buen nombre evita confusión y reduce el tiempo de decisión.

Conviene usar nombres descriptivos y funcionales. Es mejor article-card.mjml que block-1.mjml. También es preferible evitar nombres demasiado ligados a una campaña concreta. Por ejemplo, promo-banner.mjml será más útil a largo plazo que summer-sale-2026-banner.mjml.

Mantener una convención consistente también ayuda. Si usas kebab-case, úsalo en todo el proyecto: footer-legal.mjml, hero-simple.mjml, button-primary.mjml.

También puedes distinguir variantes cuando sea necesario. Por ejemplo: hero-simple.mjml, hero-image.mjml y hero-centered.mjml. Pero es importante no crear variantes innecesarias. Si dos componentes solo cambian una palabra o un color, quizá deberían ser el mismo componente con estilos o datos distintos.

Patrones que conviene evitar

Organizar componentes reutilizables en MJML también implica saber qué no hacer. El primer patrón a evitar es copiar y pegar bloques entre emails. Es rápido al principio, pero caro a medio plazo. Si el footer cambia, tendrás que actualizarlo en todos los emails donde lo hayas copiado.

Otro error habitual es crear componentes sin criterio. Separar por separar tampoco ayuda. Si cada <mj-text> vive en un archivo diferente, la plantilla será difícil de leer.

También conviene evitar mezclar estilos globales con estilos puntuales. Si cada componente redefine tipografías, colores y paddings sin seguir una base común, acabarás con un sistema inconsistente.

Por último, no hay que olvidar las limitaciones propias del email. MJML simplifica mucho la maquetación, pero los emails siguen dependiendo de clientes de correo con comportamientos distintos. Por eso es importante revisar qué partes de CSS son realmente seguras. Para profundizar en este punto, puedes leer qué partes de CSS funcionan realmente en email marketing y también el artículo sobre limitaciones reales del CSS en clientes de correo.

Organización recomendada para un workflow frontend moderno

Si trabajas en un entorno frontend moderno, puedes integrar MJML dentro de un flujo con scripts, control de versiones y generación automática.

Una estructura posible sería:

src/ emails/ templates/ components/ layouts/ styles/ data/ scripts/ build-emails.js dist/ emails/

Y en el archivo package.json podrías tener scripts como estos:

{ "scripts": { "build:emails": "node scripts/build-emails.js", "watch:emails": "mjml src/emails/templates -o dist/emails --watch" }
}

La idea es que los emails formen parte del proyecto, no que vivan como archivos sueltos en una carpeta perdida. Así puedes versionarlos, revisarlos en pull requests, automatizar la compilación y mantener consistencia entre campañas.

Este enfoque también facilita integrar MJML con otras herramientas del ecosistema frontend. Si te interesa esta parte más técnica, puedes continuar con el artículo sobre cómo integrar MJML en un workflow frontend moderno.

Documentar los componentes

Si el proyecto crece, conviene crear una pequeña documentación interna. No hace falta algo enorme. Puede bastar con un archivo README.md donde expliques qué componentes existen, cuándo usar cada uno, qué variantes hay, qué estilos globales están disponibles, cómo compilar los emails y qué criterios seguir antes de crear un componente nuevo.

Esta documentación evita que cada persona del equipo tome decisiones distintas. También reduce la carga cognitiva, porque no tienes que recordar de memoria cómo se construye cada bloque.

Accesibilidad y componentes reutilizables en emails

Cuando organizamos componentes MJML, no deberíamos pensar solo en la parte visual. También conviene tener en cuenta la accesibilidad.

Un componente reutilizable puede ayudar mucho si ya incluye buenas prácticas desde el principio: textos alternativos en imágenes relevantes, jerarquía clara, botones comprensibles, contraste suficiente y una estructura fácil de leer.

Por ejemplo, si tienes un componente de tarjeta de artículo, no debería limitarse a mostrar una imagen, un título y un botón genérico de “Leer más”. Sería más recomendable que el enlace o el botón tengan un contexto claro, especialmente para personas que navegan con lector de pantalla.

En lugar de repetir un patrón poco descriptivo en todos los emails, puedes resolverlo bien una vez y reutilizarlo en cada campaña. Para ampliar este enfoque, puedes revisar la guía sobre emails accesibles, contraste, jerarquía y lectores de pantalla.

Cómo decidir si un bloque merece ser componente

Antes de crear un nuevo componente, puedes hacerte varias preguntas. La primera es sencilla: ¿este bloque se va a repetir? Si la respuesta es sí, probablemente merece convertirse en componente.

También conviene preguntarse si tiene una responsabilidad clara. Un buen componente debe poder explicarse en una frase. Si necesitas demasiada explicación, quizá ese bloque está mezclando demasiadas funciones.

Otra pregunta útil es si depende demasiado de una campaña concreta. Si depende de una promoción única, quizá no sea reusable. En cambio, si representa un patrón que puede volver a aparecer, como una tarjeta, un CTA o un módulo de artículos, sí tiene sentido aislarlo.

Por último, piensa si ese componente mejorará la consistencia del sistema y reducirá errores futuros. Un footer legal, un botón principal o un bloque de baja de suscripción suelen beneficiarse mucho de estar centralizados.

La reutilización no consiste en crear más archivos, sino en reducir decisiones repetitivas. Un buen sistema de componentes debe hacer que crear un nuevo email sea más rápido, más claro y más fiable.

Preguntas frecuentes sobre componentes reutilizables en MJML

¿MJML permite crear componentes como en React?

No exactamente de la misma forma. MJML trabaja con su propio sistema de componentes y permite organizar archivos mediante inclusiones, atributos globales, clases y estructuras reutilizables. También existen formas más avanzadas de crear componentes personalizados, pero para la mayoría de proyectos de email marketing suele ser suficiente trabajar con parciales, layouts y estilos centralizados.

¿Cuándo debería usar mj-include?

Deberías usar <mj-include> cuando una parte del email se repite en varias plantillas o cuando separar un bloque mejora la legibilidad del archivo principal. Es especialmente útil para headers, footers, bloques legales, CTAs, módulos de artículos y estilos compartidos.

¿Es mejor tener muchos componentes pequeños o pocos componentes grandes?

Depende del proyecto, pero normalmente funciona mejor un equilibrio. Los componentes pequeños ayudan a reutilizar piezas concretas, mientras que los componentes medianos o grandes facilitan componer emails rápidamente. Lo importante es que cada componente tenga una responsabilidad clara y que la estructura completa siga siendo fácil de entender.

Reutilizar componentes también es diseñar mejor

Organizar componentes reutilizables en MJML no es solo una decisión técnica. También es una decisión de diseño, de mantenimiento y de experiencia de trabajo.

Un buen sistema de componentes evita repetir decisiones, reduce errores, mejora la coherencia visual y permite que cada nuevo email parta de una base sólida. En lugar de preguntarte cada vez cuánto padding debe tener un botón, cómo se construye el footer o qué estructura debe seguir una tarjeta, puedes apoyarte en un sistema ya definido.

Y eso tiene un impacto directo en la calidad final. Porque cuando la estructura está clara, puedes dedicar más energía a lo importante: el mensaje, la jerarquía, la claridad del contenido y la experiencia de quien recibe el email.

MJML ya te da una base mucho más amable que el HTML tradicional para emails. Pero la diferencia entre “usar MJML” y “trabajar bien con MJML” está en cómo organizas tus piezas.

Un proyecto con buenos reusable email components no solo es más cómodo para desarrollar: también es más consistente, más escalable y más fácil de mantener en el tiempo.