README

Build Laravel email templates using React components and react-email.

📚 Documentation

Quick Start Guide - Get started in 5 minutes
Examples - Practical email templates
Upgrade Guide - Migrate from v1.x to v2.0
Changelog - Version history

Installation

Install the package via composer:

composer require mscode-pl/laravel-react-email

Setup

After installing the package, publish the configuration file:

php artisan vendor:publish --provider="MsCodePL\LaravelReactEmail\LaravelReactEmailServiceProvider" --tag="react-email-config"

Install the required npm dependencies in your Laravel project:

npm install react react-email @react-email/components
# or with pnpm
pnpm add react react-email @react-email/components

Configuration

The configuration file is located at config/react-email.php. You can customize the following options:

return [
    // Path to React email templates (source .tsx files)
    'path' => resource_path('react-email'),
    
    // Path to built HTML output (Blade templates)
    'build_path' => resource_path('views/react-email'),
];

You can also set these paths via environment variables:

REACT_EMAIL_PATH=resources/react-email
REACT_EMAIL_BUILD_PATH=resources/views/react-email

Usage

Creating a new email

Use the artisan command to generate both a Mailable class and a React email template:

php artisan make:react-email WelcomeEmail

This creates:

app/Mail/WelcomeEmail.php - The Laravel Mailable class
resources/react-email/welcome-email.tsx - The React email template

Building your React email template

Edit the generated React template at resources/react-email/welcome-email.tsx:

import React from 'react';
import { Html, Head, Body, Container, Text, Button } from "@react-email/components";

interface WelcomeEmailProps {
  userName?: string;
  activationUrl?: string;
}

export default function WelcomeEmail({ userName = 'User', activationUrl = '#' }: WelcomeEmailProps) {
  return (
    <Html>
      <Head />
      <Body style={{ fontFamily: 'Arial, sans-serif' }}>
        <Container>
          <Text>Welcome, $$userName$$!</Text>
          <Text>Click the button below to activate your account:</Text>
          <Button href="$$activationUrl$$">Activate Account</Button>
        </Container>
      </Body>
    </Html>
  );
}

Note: Use $$variableName$$ syntax for variables that will be replaced with Blade variables.

Working with variables

You can use both simple and nested variables in your templates:

export default function OrderConfirmation({ 
  orderNumber = '12345',
  user = { name: 'John', email: 'john@example.com' },
  shop = { name: 'My Shop', domain: 'shop.example.com' }
}) {
  return (
    <Html>
      <Body>
        {/* Simple variable */}
        <Text>Order #$$orderNumber$$</Text>
        
        {/* Nested variables */}
        <Text>Hello $$user.name$$,</Text>
        <Text>Confirmation sent to $$user.email$$</Text>
        
        {/* Used in attributes */}
        <Button href="https://$$shop.domain$$/orders/$$orderNumber$$">
          View Order
        </Button>
      </Body>
    </Html>
  );
}

In your Mailable, pass the data structure:

public function __construct(
    public string $orderNumber,
    public array $user,
    public array $shop,
) {}

Compiling templates

Before sending emails, compile your React templates to Blade views:

php artisan react-email:build

This command compiles all .tsx files in your react-email directory to Blade templates.

Using in your Mailable

The generated Mailable class already references the compiled views:

namespace App\Mail;

use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;
use MsCodePL\LaravelReactEmail\ReactMailable;

class WelcomeEmail extends ReactMailable
{
    public function __construct(
        public string $userName,
        public string $activationUrl,
    ) {}

    public function envelope(): Envelope
    {
        return new Envelope(
            subject: 'Welcome to Our Platform',
        );
    }

    public function content(): Content
    {
        return new Content(
            html: 'react-email.welcome-email',
            text: 'react-email.welcome-email-text',
        );
    }
}

Sending emails

Send emails as usual with Laravel:

use App\Mail\WelcomeEmail;
use Illuminate\Support\Facades\Mail;

Mail::to($user)->send(
    new WelcomeEmail(
        userName: $user->name,
        activationUrl: route('activate', ['token' => $user->activation_token])
    )
);

Development

Preview server

Start the React Email dev server to preview your templates in the browser:

php artisan react-email:dev

This starts a development server (usually at http://localhost:3000) where you can preview and test your email templates with hot reload.

Automatic compilation

For development, you may want to automatically rebuild templates when they change. You can use a file watcher or add a build step to your workflow:

# Rebuild templates
php artisan react-email:build

Commands

php artisan make:react-email <Name> - Create a new Mailable and React template
php artisan react-email:build - Compile all React templates to Blade views
php artisan react-email:dev - Start the React Email preview server

How it works

Development: Create React email templates using @react-email/components
Compilation: Run react-email:build to compile React templates to static HTML Blade views
Usage: Laravel Mailables reference the compiled Blade views
Variables: Use special syntax in React which gets converted to Blade:
- Simple variables: $$variableName$$ → {{ $variableName }}
- Nested variables: $$user.email$$ → {{ $user['email'] }}
- Deep nesting: $$shop.settings.domain$$ → {{ $shop['settings']['domain'] }}

Requirements

PHP 8.1 or higher (8.5 supported)
Laravel 10.x, 11.x, or 12.x
Node.js 16 or higher
React 18+

License

MIT License. See LICENSE for more information.

mscode-pl / laravel-react-email

Maintainers

Details