@uxf/mailing

v11.117.2

Published

a month ago

Email rendering utilities and build tools

0High
0Medium
0Low

uxf

@uxf/mailing

React-based email template renderer package for developing, building, and deploying email templates.

Package Structure

@uxf/mailing/
├── build-renderers.ts     # Production build script
├── dev-runner.tsx         # Development runner (used by PHP in dev mode)
├── renderer-entry.tsx     # Bundled entry point for each template
├── renderer-plugin.ts     # esbuild plugin for virtual entry points
├── responsive.tsx         # ResponsiveRow / ResponsiveColumn helpers
├── with-preview-props.tsx # Helper for dev server preview props
└── types.ts               # TypeScript definitions

Email Component Library

react-email v6 is declared as a peerDependency and is auto-installed by the UXF tooling — components and the render function are imported from a single package:

import { Body, Container, Head, Html, render, Tailwind, Text } from "react-email";

build-renderers.ts externalizes react-email, @react-email/render, and react so the bundled template .js resolves them from the consumer's node_modules at runtime instead of inlining them.

Responsive helpers (ResponsiveRow, ResponsiveColumn) used to come from @responsive-email/react-email; they live in this package now and are imported via @uxf/mailing/responsive — no extra install needed.

Project Structure (in consuming project)

api/
├── node_modules/@uxf/mailing/
├── templates/
│   └── react/                     # Email templates
│       ├── example/
│       │   ├── example-email.tsx  # Template implementation
│       │   ├── example-email.json # Preview data
│       │   └── example-email.js   # Built output (git-ignored)
│       └── tsconfig.json
├── tsconfig.json
└── package.json

Development Workflow

Creating a New Template

Create the template file:

// 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);
}

Create the preview data file:

// templates/react/my-template.json
{
    "data": {
        "title": "My Email Template",
        "message": "Hello from my custom template!"
    }
}

Build for production:

yarn renderers:build

Building for Production

yarn tsx node_modules/@uxf/mailing/build-renderers.ts --path templates/react

This command:

Finds all .tsx files in the specified path
Bundles each template with CLI rendering logic via esbuild
Outputs a .js file next to each template
react, react-email, and @react-email/render are external (resolved from project node_modules)

Parameters:

--path, -p: Path to templates directory (required)

Testing a Built Template

node templates/react/example/example-email.js '{"data": {"title": "Test", "note": "Hello"}}'

Development Mode (PHP)

In development, PHP calls templates directly via tsx without building:

tsx node_modules/@uxf/mailing/dev-runner.tsx templates/react/example/example-email.tsx '{"data": {...}}'

dev-runner.tsx dynamically imports the template's EmailComponent and renders it.

Environment Variables

Templates access environment variables at runtime:

<Img src={`${process.env.FRONTEND_URL}/assets/mailing/logo.png`} alt="Logo" />

Variables are loaded from the project's .env file.

Scripts Reference

| Command | Description | |---------|-------------| | yarn tsx @uxf/mailing/build-renderers.ts -p <path> | Build production bundles | | yarn tsx @uxf/mailing/dev-runner.tsx <template> <json> | Run a template in dev mode |

tsconfig Requirements

The consuming project's tsconfig.json must include the templates directory and set jsx: react-jsx:

{
    "compilerOptions": {
        "jsx": "react-jsx"
    },
    "include": ["templates/react/**/*.ts", "templates/react/**/*.tsx"]
}

Troubleshooting

`React is not defined` at runtime

The tsconfig.json include field does not cover the template files. Ensure templates/react/** is included.

Build failures

Ensure template files end with .tsx
Ensure each template exports EmailComponent as a named export and a default function
Run yarn typecheck to identify type errors

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@uxf/mailing

Package Structure

Email Component Library

Project Structure (in consuming project)

Development Workflow

Creating a New Template

Building for Production

Testing a Built Template

Development Mode (PHP)

Environment Variables

Scripts Reference

tsconfig Requirements

Troubleshooting

React is not defined at runtime

Build failures

`React is not defined` at runtime