repository·main·Indexed 22 days ago
https://github.com/shellscape/jsx-emailA React and TypeScript-based framework for building responsive, high-quality email templates. It provides a specialized component library to abstract email client rendering inconsistencies and includes a CLI tool, create-mail, for project scaffolding. The framework is provider-agnostic and supports integrations with AWS SES, Loops, Nodemailer, Postmark, Resend, Plunk, and SendGrid. It features a plugin system for CSS inlining, HTML minification, cleaning unused CSS, and URL modification.
JSX email includes several features designed to improve developer experience and template reliability:
<Suspense> and async within components.The Avatar component handles missing images using a specific fallback hierarchy:
Visible Fallback Text Order:
fallback prop.name prop."?".Accessibility (Alt Text) Order:
decorative={false}): Uses the order: alt prop $\rightarrow$ name prop $\rightarrow$ resolved visible fallback text.decorative={true}): Renders with role="presentation" and aria-hidden="true".The Tailwind component is not compatible with standard Tailwind Plugins out of the box because it uses UnoCSS as its engine.
Instead of Tailwind plugins, you should use equivalent UnoCSS presets, Community Presets, or Transformers. If you require a specific Tailwind plugin, you may need to port it to an UnoCSS preset.
jsx-email v2 introduces a plugin system that allows you to hook into different stages of the rendering process (before, during, or after core rendering). This is ideal for tasks like:
Core functionality for minifying and prettifying has been moved to separate plugins. This allows for smaller bundles and is particularly useful in restricted environments like Cloudflare Workers.
The v2 Preview app has moved from runtime rendering to a pre-rendering model. This makes the preview faster and more reliable by removing Vite-related dependency and optimization issues. A watcher is used to provide immediate updates when templates change.
Breaking Change: Local, relative imports of assets (such as images) within templates are currently not supported due to the new rendering pipeline.
New Capability: You can now exclude specific files from being shown in the preview app.
If you are using the jsx-email API instead of the CLI and need to support CSS imports, you cannot use the render method directly on a file that contains CSS imports. Instead, you must use the compile API first.
Workflow:
compile API to process the file.Template from the compiled output.Template to the render method.render method from jsx-email. Once rendered, pass the resulting HTML string to your provider's SDK or API. This allows you to use JSX email with virtually any service that accepts a string for content input.While inlining CSS improves compatibility, it significantly increases the byte size of the email HTML.
Warning: Email Clipping Email clients like Gmail will clip emails that exceed certain size limits, forcing recipients to click a "Show Full Message" button.
Best Practice
Monitor your console output when running the render method; jsx-email will alert you if the resulting HTML size is too large.
JSX email is provider-agnostic. Since it renders emails as strings, you can use it with any email service provider that accepts a string payload via an API.
Supported integrations include:
Install the plugin via npm:
npm install @jsx-email/plugin-urlThe @jsx-email/plugin-url plugin modifies URLs within the rendered email HTML. Its primary feature is the append option, which allows you to automatically append specific URL parameters to matching URL attributes in your email templates.
Note: This plugin is not loaded automatically by jsx-email. You must manually add it to the plugins array in your configuration.