Quick Start
In this doc you'll find information on quickly getting started using Email Craft. 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
- 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-email-craft 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-email-craft@latest$ npx create-email-craft@latestThis command will install and execute create-email-craft, 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 Email Craft, as it contains infmroation on the project and template that was just created.
Existing Projects
The happy path for adding Email Craft to an existing project is by using the Email Craft CLI:
Install
Install the from your command line
pnpm install email-craftpnpm install email-craftbun install email-craftbun install email-craftnpm install email-craftnpm install email-craftyarn install email-craftyarn install email-craftIf you want to avoid global installation, you can use pnpm dlx, npx, or yarn instead like so:
$ pnpm dlx emailcraft <command>$ pnpm dlx emailcraft <command>Create A Template
First, we'll create a directory for our email templates, and then add a new template:
$ mkdir ./emails
$ emailcraft create BatmanEmail --out=./emails$ mkdir ./emails
$ emailcraft create BatmanEmail --out=./emailsThis 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. Email Craft 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 Email Craft 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
$ emailcraft preview ./emails# MacOS and Linux
$ emailcraft preview ./emailsINFO
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:
$ emailcraft build ./emails/BatmanEmail.tsx$ emailcraft build ./emails/BatmanEmail.tsxTIP
Please use email help build to view optional flags, including providing props and setting the output path.