Setting up react-email in a monorepo: A complete guide for 2025

Want to make email templates with React but don't know where to start?
As your SaaS or startup grows, you'll need multiple emails — onboarding, password resets, promotions, newsletters. Without structure, they end up scattered across repos and hard to maintain.

This guide shows you how to organize all your React Email templates in one place using a monorepo with npm workspaces.

What is a Monorepo and Why Use It for Email Templates?

A monorepo keeps all your code in one place — like having all your tools in a single toolbox.

For React email templates, this means you can:

✅ Share components between transactional and marketing emails
✅ Keep all your email code organized in one spot
✅ Test changes across all templates at once
✅ Deploy updates more easily

👉 By the end, you'll have a scalable setup ready for any project in 2025 and beyond.

Setting Up Your Monorepo

First, create the project structure:

mkdir email-templates-monorepo
cd email-templates-monorepo
npm init -y

Enable npm workspaces inside package.json:

{
  "name": "email-templates-monorepo",
  "workspaces": ["packages/*"]
}

Creating Your Email Package

Let's set up the package for your transactional emails:

mkdir -p packages/transactional
cd packages/transactional
npm init -y

Install the necessary dependencies:

npm install @react-email/components react react-dom

Writing Your First Email Template

Inside packages/transactional/emails/WelcomeEmail.tsx:

import * as React from 'react';
import { Html, Text } from '@react-email/components';

export const WelcomeEmail = () => (
  <Html>
    <Text>Welcome to our app! We're glad to have you 🎉</Text>
  </Html>
);

Setting Up the Preview Server

Update your packages/transactional/package.json:

{
  "scripts": {
    "dev": "email dev",
    "export": "email export"
  }
}

Start the preview server:

npm run dev

Now visit http://localhost:3000 to preview your email templates.

Organizing Your Templates

Here's a recommended monorepo structure:

  email-templates-monorepo/
  ├── packages/
  │ ├── transactional/
  │ │ ├── emails/
  │ │ │ ├── WelcomeEmail.tsx
  │ │ │ ├── PasswordReset.tsx
  │ │ │ └── OrderConfirmation.tsx
  │ │ └── package.json
  │ └── marketing/
  │ ├── emails/
  │ │ ├── Newsletter.tsx
  │ │ └── Promotion.tsx
  │ └── package.json
  └── package.json

Sharing Components Between Templates

Create a shared components package:

mkdir -p packages/shared
cd packages/shared
npm init -y

Example: packages/shared/components/Button.tsx

import * as React from 'react';

export const Button = ({ children, ...props }) => (
  <button
    style={{
      padding: '12px 20px',
      borderRadius: '4px',
      background: '#007bff',
      color: 'white',
      border: 'none',
    }}
    {...props}
  >
    {children}
  </button>
);

Now you can import <Button /> across multiple templates.

Testing Your Email Templates

With React Email, testing is simple:

Run npm run dev
Open http://localhost:3000
Preview emails in different clients and devices

You can catch layout issues early and ensure cross-client compatibility.

Best Practices for React Email in a Monorepo

📦 Keep shared components in a dedicated package
🔒 Use TypeScript for type safety
🎨 Maintain consistent styling across all templates
📖 Document your components well
🔄 Set up CI/CD to export and deploy templates

Next Steps

Now that your monorepo is set up, you can:

Add more transactional & marketing email templates
Expand your shared component library
Integrate CI for automated builds
Add Jest tests for reliability
Adopt a design system for branding consistency

Conclusion

You now have a scalable React Email monorepo setup using npm workspaces.
This structure keeps your templates organized, shareable, and production-ready.

👉 If you'd rather skip setup and start with beautiful, responsive, production-ready templates, check out our Premium React Email Templates Bundle.

Happy coding 🚀