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.
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:
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-mail 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):
$ npx create-mail my-email-projectThis command will install and execute create-mail, create a my-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 information on the project and template that was just created.
The happy path for adding JSX email to an existing project is by using the JSX email CLI:
pnpm add jsx-emailIf you want to avoid global installation, you can use pnpm dlx, npx, or yarn instead like so:
$ pnpm dlx email <command>First, we’ll create a directory for our email templates, and then add a new template:
$ mkdir ./emails
$ email create BatmanEmail --out=./emailsThis command will create a new template named BatmanEmail.tsx in the ./emails directory.
If you’d rather create a .jsx file, use the --jsx flag
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:
# MacOS and Linux
$ email preview ./emailsWindows 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.
Please use email help preview to view optional flags, including setting the port.
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:
$ email build ./emails/BatmanEmail.tsxPlease use email help build to view optional flags, including providing props and setting the
output path.