Skip to content

## 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:

- Node Fundamentals
- NPM Fundamentals
- Executing Local NPM Packages
- `npx` and `pnpm exec`
- How to use relative paths on windows CMD?

## Prerequisites ​

- Node.js v18.0.0+
- React v18.2.0

## 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

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