We’ve created this guide to help new contributors understand and navigate the React Email codebase.

​
Top-level directories

After cloning the React Email repository you will see a few root-level directories. Here’s a brief overview of each:
DirectoryDescription
appsHere you can find all of the apps related to our online presence, like:
benchmarksWe make benchmarks from version-to-version to demonstrate data-observable performance gains with metrics like p99 and p75.For example, see the Improved Performance for Tailwind Emails benchmark.
packagesMost contributions will be made to the packages in this directory.This directory contains all our published NPM packages. Each subdirectory is a single component published as its own package, with the exception of a few packages that serve as shared configuration.
Feel free to open a discussion if you have suggestions on how to better structure these packages to make them more manageable and approachable.

​
Multiple packages

The react-email repository is a pnpm monorepo, which means it contains multiple packages. Because we use pnpm, you will need to use pnpm to install and run each package. If you do not have pnpm installed, we recommend you install it using corepack: 
corepack enable
corepack prepare pnpm@latest --activate
Currently, we have the following packages:
Most of these packages are very small and can be easily understood by reading the code, so feel free to explore.

​
Turborepo

We encourage using turborepo to manage the packages. It’s often helpful to install Turborepo globally to make it easier to run commands in any of the repositories. With a global installation, running turbo build in any of the packages will build both the package you are on as well as the dependent packages. The global installation handles version mismatching as well.

​
The React Email CLI

The CLI is built using commander, a CLI builder for node. It handles parsing of command line arguments and ensuring that the syntax for the command is as expected. The build, dev, and start commands all depend on the user first installing @react-email/preview-server. Locally installing the preview server also includes all the required dependencies so you can run the necessary commands. nypm and jiti work together to first ensure @react-email/preview-server is installed and then to import it into the CLI. The Preview Server and the CLI work together. The CLI detects changes to files in the user’s dependency graph with chokidar and then sends the updated files to the Preview Server using socket.io. Other details, like the path to the user’s emails directory, are handled through environment variables.

​
The Preview Server

The Preview Server is a Next.js app that uses esbuild at runtime to bundle the user’s email templates and then renders them using the render utility. As changes from the CLI are passed through socket.io to the Preview Server, the preview updates automatically.

​
Testing

For testing, we use vitest. We prefer to define globals and run tests under the happy-dom environment. We do not strictly enforce testing coverage, but encourage it. For help testing, see our Development workflow guide.
The @react-email/render package’s renderAsync does a fair bit of magic to simulate edge and other environments that are not supported by happy-dom. For this use case, we override the environment on a per-file basis for its tests

​
Linting

We use biomejs for linting and formatting. Both the linting and formatting are ensured by our GitHub CI so make sure you lint and format your code (pnpm lint:fix) before opening a PR or asking for a review on it. For help linting and formatting, see our Development workflow guide on linting.

​
Building

We use tsup to build most packages. (The only exception for this is the @react-email/tailwind package which currently uses vite due to a few issues with tsup and tailwindcss’s bundling.) For help building packages, see our Development workflow guide.
Building in each package will run tsup with a few settings, typically src/index.ts --format esm,cjs --dts --external react. Tsup handles building both ESM and CJS versions along with the type definitions exported from the entry point, src/index.ts, without bundling react, which can cause issues.

​
Why build before publishing?

We build most of the packages before publishing for a few reasons:
  1. All the exported types can be imported from the same place the JavaScript is imported
  2. We have proper CommonJS and ES Modules support
  3. Code that isn’t exported is not published or downloaded