Tooling for authoring react-email templates and rendering them to HTML from Node — an esbuild-based production build step, a tsx dev runner, responsive layout helpers, and a preview-props helper.
Use this in a project that writes transactional emails as React (react-email) components and needs to turn them into HTML from a Node/CLI process (in UXF projects a PHP backend shells out to Node to produce the final HTML). It provides:
build-renderers — bundles each template into a standalone, self-executing .js renderer.dev-runner — renders a single template on the fly with tsx, no build step.responsive — ResponsiveRow / ResponsiveColumn layout helpers for email-safe multi-column rows.with-preview-props — attaches preview data to a template for the react-email preview UI.It is not an email-sending package (no SMTP/transport) and not a component library — the email components (Html, Body, Text, Tailwind, render, …) come from the react-email peer dependency.
yarn add @uxf/mailing"type": "module") and requires Node >= 26.react ^19.3.0, react-dom ^19.3.0, react-email ^6.11.0.tsx ^4.23.12 is also a peer dependency. The package ships its entry points as raw .ts/.tsx, so build-renderers and dev-runner are executed with tsx rather than node — see Build & run. npm installs it automatically; yarn and pnpm need it added explicitly.esbuild, glob, yargs, dotenv.The package ships an exports map — import only these subpaths (there is no root/index export):
renderer-entry.tsx and renderer-plugin.ts are internal build machinery and are not part of the public surface.
A template is a .tsx file that exports a named EmailComponent (rendered to HTML) plus a default export that wires up preview data for the react-email preview UI. The component receives EmailOptions-shaped props ({ data }).
// templates/react/my-template.tsx
import { Body, Container, Head, Html, pixelBasedPreset, Tailwind, Text } from "react-email";
import { withPreviewProps } from "@uxf/mailing/with-preview-props";
import previewProps from "./my-template.json";
export function EmailComponent(props: { data: { title: string; message: string } }) {
return (
<Tailwind config={{ presets: [pixelBasedPreset] }}>
<Html lang="cs">
<Head>
<title>{props.data.title}</title>
</Head>
<Body className="mx-auto max-w-[600px] p-5 font-sans">
<Container>
<Text>{props.data.message}</Text>
</Container>
</Body>
</Html>
</Tailwind>
);
}
export default function MyTemplate() {
return withPreviewProps(EmailComponent, previewProps);
}
// templates/react/my-template.json
{
"data": {
"title": "My Email Template",
"message": "Hello from my custom template!"
}
}
Render it in dev, or build a production bundle:
# dev: render on the fly (no build)
tsx node_modules/@uxf/mailing/dev-runner.tsx templates/react/my-template.tsx '{"data": {"title": "Hi", "message": "Hello"}}'
# production: bundle every template under the path into a sibling .js
tsx node_modules/@uxf/mailing/build-renderers.ts --path templates/react
The JSON argument is the top-level EmailOptions object; its data field is passed to the component as props.data.
withPreviewPropsimport { withPreviewProps } from "@uxf/mailing/with-preview-props";
withPreviewProps<Data extends AnyObject, Props extends EmailOptions<Data>>(
Component: FunctionComponent<Props>,
props: Props,
): ReactElement;
Attaches props to Component.PreviewProps (consumed by the react-email preview UI) and returns <Component data={props.data} />. Use it in the template's default export, passing the named EmailComponent and the imported preview JSON.
responsiveEmail-safe multi-column layout built from nested tables. Columns are declared with span (relative width); rows warn in the console above 3 columns.
import { ResponsiveColumn, ResponsiveRow } from "@uxf/mailing/responsive";
<ResponsiveRow maxWidth={600} paddingLeft={16} paddingRight={16}>
<ResponsiveColumn span={2} style={{ backgroundColor: "green" }} />
<ResponsiveColumn span={1} style={{ backgroundColor: "red" }} />
</ResponsiveRow>;
ResponsiveRowProps — table attributes plus maxWidth, paddingLeft, paddingRight, paddingTop, paddingBottom (numbers, in px). padding* and maxWidth are removed from the style prop and set via the dedicated props instead. maxWidth (default 600) is the width of the whole row, left and right padding included; the columns share what is left in proportion to their span.ResponsiveColumnProps — table attributes plus span?: number (default 1) and tdProps (forwarded to the inner <td>).isResponsiveColumn(node) — type guard; createResponsiveRow / createResponsiveColumn are the factories the default ResponsiveRow / ResponsiveColumn are built from.typesimport type { AnyObject, BuildResult, EmailOptions } from "@uxf/mailing/types";
EmailOptions<Data extends AnyObject = AnyObject> — { data: Data }, the props shape every template receives.AnyObject — Record<string, any>.BuildResult — per-file result metadata produced by build-renderers.build-renderers (production)tsx node_modules/@uxf/mailing/build-renderers.ts --path templates/react
--path, -p (required) — templates directory. Globs every **/*.tsx under it.target: es2022, platform: node, JSX automatic) into a .js file next to the source.node_modules, not inlined): react, react-dom, react/jsx-runtime, react-email, yargs.Each bundle is a self-executing renderer. Run it with a JSON argument or a --config file:
# JSON string
node templates/react/my-template.js '{"data": {"title": "Test", "message": "Hello"}}'
# or read the JSON from a file
node templates/react/my-template.js --config templates/react/my-template.json
It renders the template's named EmailComponent and prints the HTML to stdout.
dev-runner (development)tsx node_modules/@uxf/mailing/dev-runner.tsx <template-path> <json-data>
Dynamically imports the template's named EmailComponent, renders it with the given JSON, and prints the HTML. No build step; it also loads a project .env via dotenv/config.
Templates can read process.env at render time, e.g.:
<Img alt="Logo" src={`${process.env.FRONTEND_URL}/assets/mailing/logo.png`} />
dev-runner loads variables from the project .env (dotenv/config). Production .js bundles do not load .env themselves — the caller must supply the environment.
The consuming project's tsconfig.json must set jsx: "react-jsx" and include the templates directory:
{
"compilerOptions": {
"jsx": "react-jsx"
},
"include": ["templates/react/**/*.ts", "templates/react/**/*.tsx"]
}
EmailComponent (this is what gets rendered) and a default function (supplies PreviewProps for the preview UI). The runners import EmailComponent, not the default..tsx; build-renderers only globs **/*.tsx.react, react-dom, react-email (and yargs) are external in built bundles — they must be installed in the runtime's node_modules.ResponsiveColumns per ResponsiveRow; more logs a console warning. Set row padding/maxWidth via the dedicated props, not style.React is not defined at runtime — the tsconfig.json include does not cover the template files; ensure templates/react/** is included and jsx: "react-jsx" is set..tsx, each exports a named EmailComponent plus a default function, and run tsc --noEmit (yarn typecheck) to surface type errors.