/

  • Analyticsnpmv15.2.1

    • Overview
  • Apollonpmv15.2.1ESM

    • Overview
  • Browserslist-confignpmv15.2.1

    • Overview
  • CMSnpmv15.2.1

    • Overview
    • ContentBuilder
    • InviteUserForm
    • LoginForm
    • RenewPasswordForm
    • WysiwygInput
  • Corenpmv15.2.1

    • Overview
  • Core-Reactnpmv15.2.1

    • Overview
  • DataGridnpmv15.2.1

    • Overview
    • DataGrid
    • DataGridCustomExample
    • ExportButton
    • FilterList
    • Filters
    • FiltersButton
    • FulltextInput
    • HiddenColumns
    • HiddenColumnsButton
    • Pagination
    • RowCounts
    • RowsPerPageSelect
    • SelectedRowsToolbar
    • TableV2
    • ToolbarControl
    • ToolbarCustoms
    • ToolbarTabs
  • Datepickernpmv15.2.1

    • Overview
  • DnDnpmv15.2.1

    • Overview
  • E2E-Playwrightnpmv15.2.1

    • Overview
  • Eslint-confignpmv15.2.1

    • Overview
  • Formnpmv15.2.1

    • Overview
    • AvatarFileInput
    • CheckboxButton
    • CheckboxInput
    • CheckboxList
    • ColorRadioGroup
    • Combobox
    • DatePickerInput
    • DateRangePickerInput
    • DatetimePickerInput
    • Dropzone
    • FileInput
    • Form
    • FormRenderer
    • GpsInput
    • MoneyInput
    • MultiCombobox
    • MultiSelect
    • NumberInput
    • PasswordInput
    • RadioGroup
    • Select
    • TextInput
    • Textarea
    • TimePickerInput
    • Toggle
  • Icons-generatornpmv15.2.1

    • Overview
  • Localizenpmv15.2.1

    • Overview
  • Mailingnpmv15.2.1

    • Overview
  • Page-Buildernpmv15.3.0ESM

    • Overview
  • Page-Builder-CMSnpmv15.3.0ESM

    • Overview
  • Page-Builder-Webnpmv15.3.0ESM

    • Overview
  • Resizernpmv15.2.1

    • Overview
  • Routernpmv15.2.1

    • Overview
  • Scriptsnpmv15.2.1

    • Overview
  • Sentrynpmv15.2.1ESM

    • Overview
  • Smart-addressnpmv15.2.1

    • Overview
  • Stylesnpmv15.2.1

    • Overview
  • UInpmv15.2.1

    • Overview
    • Accordion
    • AlertBubble
    • AnnouncementBar
    • Avatar
    • AvatarFileInput
    • Badge
    • Button
    • ButtonGroup
    • ButtonList
    • Calendar
    • Checkbox
    • CheckboxButton
    • CheckboxInput
    • CheckboxList
    • Chip
    • ColorRadio
    • ColorRadioGroup
    • Combobox
    • DatePicker
    • DatePickerInput
    • DateRangePicker
    • DateRangePickerInput
    • DatetimePicker
    • DatetimePickerInput
    • Dialog
    • Dropdown
    • Dropzone
    • ErrorMessage
    • FileInput
    • FlashMessages
    • FormComponent
    • Icon
    • IconButton
    • ImageGallery
    • InfoBox
    • Input
    • Label
    • Layout
    • Lightbox
    • ListItem
    • Loader
    • Lozenge
    • Menu
    • Message
    • Modal
    • ModalDialog
    • ModalHeader
    • MultiCombobox
    • MultiSelect
    • Pagination
    • Paper
    • Popover
    • Radio
    • RadioGroup
    • RasterImage
    • Select
    • Switch
    • Tabs
    • TextInput
    • TextLink
    • Textarea
    • TimePicker
    • TimePickerInput
    • Toggle
    • Tooltip
    • Typography
  • Wysiwygnpmv15.2.1

    • Overview
Previous← Localize overviewNextPage-Builder overview →

@uxf/mailing

npm

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.

When to use

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.

Installation

yarn add @uxf/mailing
  • ESM-only ("type": "module") and requires Node >= 26.
  • Peer dependencies the consuming project must provide: 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.
  • Bundled dependencies (nothing to install): esbuild, glob, yargs, dotenv.

Public entry points

The package ships an exports map — import only these subpaths (there is no root/index export):

Import pathKindExports
@uxf/mailing/with-preview-propsmodulewithPreviewProps
@uxf/mailing/responsivemoduleResponsiveRow, ResponsiveColumn, isResponsiveColumn, createResponsiveRow, createResponsiveColumn, and types ResponsiveRowProps, ResponsiveColumnProps, BaseSectionProps
@uxf/mailing/typestypesEmailOptions<Data>, AnyObject, BuildResult
@uxf/mailing/build-renderersCLI scriptrun via tsx (see Build & run)
@uxf/mailing/dev-runnerCLI scriptrun via tsx (see Build & run)

renderer-entry.tsx and renderer-plugin.ts are internal build machinery and are not part of the public surface.

Quick start

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.

API

withPreviewProps

import { 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.

responsive

Email-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.

types

import 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 & run

build-renderers (production)

tsx node_modules/@uxf/mailing/build-renderers.ts --path templates/react
  • --path, -p (required) — templates directory. Globs every **/*.tsx under it.
  • Bundles each template with esbuild (ESM, minified, target: es2022, platform: node, JSX automatic) into a .js file next to the source.
  • Externals (resolved from the runtime's 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.

Environment variables

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.

tsconfig requirements

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"]
}

Gotchas

  • ESM + Node ≥ 26 only. The package has no root export — always import from a subpath listed above.
  • Every template must export a named EmailComponent (this is what gets rendered) and a default function (supplies PreviewProps for the preview UI). The runners import EmailComponent, not the default.
  • Template files must end in .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.
  • Keep to at most 3 ResponsiveColumns per ResponsiveRow; more logs a console warning. Set row padding/maxWidth via the dedicated props, not style.

Troubleshooting

  • 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.
  • Build failures — confirm templates end with .tsx, each exports a named EmailComponent plus a default function, and run tsc --noEmit (yarn typecheck) to surface type errors.