Email Builder Library based on @usewaypoint/email-builder - A React component for building responsive email templates

Una librería de editor de emails basada en React y TypeScript, construida sobre @usewaypoint/email-builder. Permite crear emails responsivos de manera visual con una interfaz intuitiva.
- 📧 Editor Visual: Interfaz drag-and-drop para construir emails
- 🎨 Bloques Predefinidos: Avatar, Button, Text, Image, Columns, Divider, Spacer, HTML
- 🎯 Panel de Configuración: Edición de propiedades en tiempo real (Inspector)
- 🎨 Panel de Estilos: Control global de colores, fuentes y espaciado
- 📱 Responsive: Los emails generados son compatibles con todos los clientes
- 🎭 Interfaz Limpia: Modal con editor central y panel de configuración lateral
- 🌗 Modo Oscuro: Soporte nativo para tema claro y oscuro con un simple prop
- 🖥️ Vista Desktop/Mobile: Previsualización en diferentes dispositivos
- 👁️ Modo Preview: Vista previa en tiempo real del email renderizado
- 📄 Renderizado Solo Lectura: Componente para mostrar emails guardados
- 💾 Exportación/Importación: Soporte para JSON y HTML
- 🖼️ Gestión de Imágenes: Soporte para subida personalizada de imágenes
- 🌍 Multiidioma: Soporte integrado para 9 idiomas y capacidad de locales personalizados
- 🧩 Universal: Usable en React, Vanilla JS, Vue, Angular, etc.
``bash
npm install email-template-builder
$3
Esta librería requiere las siguientes dependencias en tu proyecto:
`bash
npm install react react-dom @mui/material @mui/icons-material @emotion/react @emotion/styled
`🚀 Uso en React
Ahora es más simple que nunca. Importa directamente el componente
:`tsx
import React, { useState } from 'react';
import { EmailEditor, TEditorConfiguration } from 'email-template-builder';function App() {
const [editorOpen, setEditorOpen] = useState(false);
// Estado opcional para controlar el template externamente
const [template, setTemplate] = useState(undefined);
// Variables personalizadas para insertar en el texto
const customVariables = [
{
key: 'user_name',
name: 'Nombre del Usuario',
description: 'Nombre completo del usuario',
exampleValue: 'Juan Pérez'
}
];
// Opcional: Manejar la subida de imágenes
const handleImageUpload = async (file: File): Promise => {
// Lógica para subir a tu servidor (S3, Cloudinary, etc.)
const formData = new FormData();
formData.append('file', file);
const response = await fetch('/api/upload', { method: 'POST', body: formData });
const data = await response.json();
return data.url;
};
// Opcional: Guardar el template
const handleSave = (document: TEditorConfiguration) => {
console.log('Guardando template:', document);
// api.saveTemplate(document);
};
return (
<>
open={editorOpen}
onClose={() => setEditorOpen(false)}
// Callbacks principales
onSave={handleSave}
onChange={(document) => setTemplate(document)}
onUploadImage={handleImageUpload}
// Configuración inicial
template={template}
variables={customVariables}
// Personalización
locale="es" // 'es', 'en', 'pt', 'it', 'fr', 'de', 'nl', 'ca'
darkMode={false} // Activar modo oscuro
customLocale={{ // Sobrescribir textos específicos
"topbar_save": "Guardar Cambios"
}}
/>
>
);
}
export default App;
`🌐 Uso en Vanilla JS / Otros Frameworks
Puedes usar la librería fuera de React (Vue, Angular, Svelte, Vanilla JS) usando
mountEmailEditor.`javascript
import { mountEmailEditor } from 'email-template-builder';// 1. Puedes pasar el elemento DOM o un selector CSS
const editor = mountEmailEditor('#editor-container', {
open: true,
locale: 'es',
darkMode: true, // Soporte para modo oscuro
variables: [
{ key: 'name', name: 'Nombre', exampleValue: 'Usuario' }
],
template: { / JSON inicial opcional / },
onClose: () => {
console.log('Cerrado');
editor.update({ open: false }); // Actualizar prop para cerrar
},
onChange: (doc) => {
console.log('Cambio:', doc);
},
onSave: (document) => {
console.log('Guardado:', document);
},
onUploadImage: async (file) => {
// Tu lógica de subida
return 'https://example.com/image.jpg';
}
});
// 2. Métodos disponibles
// Actualizar propiedades en cualquier momento
editor.update({
variables: newVariables,
open: true,
darkMode: false
});
// Desmontar (limpieza)
// editor.unmount();
`🖥️ Renderizado Server-Side (SSR) / Node.js
Si necesitas generar el HTML del email desde un proceso backend o script sin interfaz gráfica:
`javascript
import { renderEmail } from 'email-template-builder';// Tu configuración JSON guardada
const myTemplateJson = { ... };
// Generar HTML estático
const htmlOutput = renderEmail(myTemplateJson);
console.log(htmlOutput); // ...
`📖 API
$3
Componente principal que renderiza el modal del editor.
Props:
| Prop | Tipo | Default | Descripción |
|------|------|---------|-------------|
|
open | boolean | - | Requerido. Controla si el modal está visible. |
| onClose | () => void | - | Requerido. Callback para cerrar el modal. |
| onSave | (doc: TEditorConfiguration) => void | - | Callback al hacer clic en Guardar. |
| onChange | (doc: TEditorConfiguration) => void | - | Callback invocado en cada cambio del template. |
| template | TEditorConfiguration | - | Objeto JSON con el estado inicial del email. |
| variables | EmailVariable[] | [] | Lista de variables para insertar en el texto. |
| locale | SupportedLocale | 'es' | Idioma de la UI ('es', 'en', 'fr', 'de', 'it', 'pt', 'pt-br', 'nl', 'ca'). |
| customLocale | Record | - | Objeto para sobrescribir traducciones específicas o añadir nuevas. |
| darkMode | boolean | false | Activa el tema oscuro de la interfaz. |
| onUploadImage | (file: File) => Promise | - | Función asíncrona para manejar la subida de imágenes. Debe retornar la URL. |$3
Función para montar el editor en entornos no-React. Retorna un objeto con:
-
update(newProps): Actualiza las props del editor.
- unmount(): Desmonta el componente y limpia el DOM.$3
Nota: Ya no es necesario usar este provider para envolver el editor, ya que
maneja su propio contexto y estilos de forma aislada. Se mantiene exportado para retrocompatibilidad.$3
Componente para visualizar templates guardados en modo solo lectura (usa un iframe aislado).
`tsx
template={myTemplateJson}
minHeight="600px"
/>
`🏗️ Desarrollo
$3
- Node.js >= 18.x
- pnpm (recomendado) o npm
$3
`bash
Clonar el repositorio
git clone https://github.com/beweos/email-editor.git
cd email-editorInstalar dependencias
pnpm installIniciar servidor de desarrollo
pnpm dev
`$3
-
pnpm dev - Inicia el servidor de desarrollo con el ejemplo
- pnpm build:lib - Construye la librería para producción
- pnpm preview - Preview de la build
- pnpm type-check - Verifica los tipos TypeScript🏗️ Build de la Librería
Para construir la librería para distribución:
`bash
pnpm build:lib
`Esto generará en
dist/:
- index.js - ES Module
- index.cjs - CommonJS
- index.d.ts - Declaraciones de TypeScript📚 Tecnologías
- React 18 - Framework UI
- TypeScript - Type safety
- Material-UI (MUI) - Componentes UI
- Emotion - CSS-in-JS
- Vite - Build tool
- Zustand - State management
- Zod - Validación
- @usewaypoint/email-builder - Motor del editor
🎯 Componentes del Editor
$3
El modal incluye dos paneles principales:
#### 📝 Panel Central - Editor
- Editor: Vista de edición con drag-and-drop de bloques
- Preview: Vista previa en tiempo real del email renderizado
- Controles:
- Toggle entre vista Desktop y Mobile
- Botón para cambiar entre Editor y Preview
#### 🎨 Panel Derecho - Inspector/Styles
Panel lateral con dos pestañas:
- Styles: Configuración global del email (colores de fondo, canvas, fuentes, bordes)
- Inspect: Propiedades del bloque seleccionado (se activa automáticamente al hacer clic en un bloque del editor)
$3
- Avatar: Imágenes de perfil circulares
- Button: Botones con estilos personalizables
- Text: Texto con formato rico
- Heading: Encabezados (H1-H6)
- Image: Imágenes responsive con subida personalizada
- Columns: Layouts de columnas flexibles
- Container: Contenedores con padding
- Divider: Líneas divisoras horizontales
- Spacer: Espaciado vertical personalizable
- HTML: Código HTML personalizado
🤝 Contribuir
Las contribuciones son bienvenidas! Por favor:
1. Fork el proyecto
2. Crea tu feature branch (
git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push al branch (git push origin feature/AmazingFeature`)MIT © [Beweos]
Esta librería está construida sobre el excelente trabajo de:
- @usewaypoint/email-builder
- Material-UI
- React Email
Para reportar bugs o solicitar features, por favor abre un issue.
---
Hecho con ❤️ por Beweos