Appearance

Quick Start ​

In this doc you'll find information on quickly getting started using JSX email. For more in-depth information, please see the other sections of our Documentation.

INFO

This guide, along with the rest of the documentation here, assume that the reader has fundamental Node and NPM skills and is familiar with using command line tools on Window, Linux, or Mac OS.

For those not familiar with the bits above, here are some links to resources that we'd recommend reading before working with this project:

Prerequisites ​

New Projects ​

If you're starting a new project — whether that's a project solely for email templates, or a project that will eventually host additional code — our create-jsx-email utility is a perfect choice, and the fastest way to get started. The utility will scaffold a new project and get everything ready for developing new email templates. To begin, make sure you have a terminal (or command line) open and your current working directory is the directory you'd like to create a new project. Run the following command in your terminal (without the $ symbol):

console
$ npm create jsx-email
$ npm create jsx-email

This command will install and execute create-jsx-email, create a email-project directory, and add a starter template.

While the Existing Projects section below can be safely skipped, the information beneath it is useful and worth giving a read before working with JSX email, as it contains infmroation on the project and template that was just created.

Existing Projects ​

The happy path for adding JSX email to an existing project is by using the JSX email CLI:

Install ​

Install the from your command line

console
pnpm add jsx-email
pnpm add jsx-email
console
bun add jsx-email
bun add jsx-email
console
npm add jsx-email
npm add jsx-email
console
yarn add jsx-email
yarn add jsx-email

If you want to avoid global installation, you can use pnpm dlx, npx, or yarn instead like so:

shell
$ pnpm dlx email <command>
$ pnpm dlx email <command>

Create A Template ​

First, we'll create a directory for our email templates, and then add a new template:

sh
$ mkdir ./emails
$ email create BatmanEmail --out=./emails
$ mkdir ./emails
$ email create BatmanEmail --out=./emails

This command will create a new template named BatmanEmail.tsx in the ./emails directory.

TIP

If you'd rather create a .jsx file, use the --jsx flag

Superstruct ​

Superstruct is a fantastic validation package that predates zod and yup. It's smaller and faster than alternatives and uses a delightful API without chaining or cruft. JSX email uses it as an option for defining prop types and creating props for use in email previews.

Email Previews ​

One of the major benefits of JSX email over alternatives is our incredibly slim and fast preview server, which requires no additional dependency installation, complex mounting, or difficult setup rules for monorepos. To run the preview server, run the following command in your terminal:

sh
# MacOS and Linux
$ email preview ./emails
# MacOS and Linux
$ email preview ./emails

INFO

Windows paths are different than MacOS or Linux paths. ./emails above will not work on Windows. Please see the link above regarding Windows relative paths if you are unfamiliar with how they work on the Command Line

The CLI will startup a preview server and open a new browser tab at http://localhost:55420. It's that simple.

TIP

Please use email help preview to view optional flags, including setting the port.

Building Your Template ​

The next step is to build your template. This can be done with the CLI, or with the render method in code. While most people will need to render emails dynamically at runtime using render, the CLI is capable of rendering both static and dynamic emails that take props as input. To build your email into an HTML document, run:

sh
$ email build ./emails/BatmanEmail.tsx
$ email build ./emails/BatmanEmail.tsx

TIP

Please use email help build to view optional flags, including providing props and setting the output path.