Preview Server UI
Relevant source files
The following files were used as context for generating this wiki page:
The Preview Server UI provides a browser-based development environment for visualizing and testing React-based email templates. It allows developers to view templates in real-time, modify rendering properties, and validate email markup against industry standards and client compatibility requirements.
The interface is primarily delivered through the @react-email/ui package and is integrated with the React Email CLI to facilitate local development. It supports features such as hot reloading, dark mode emulation, and a syntax-highlighted editor for template props.
Sources: README.md:1-24, packages/ui/readme.md:1-20, SKILL.md:417-438
Core Architecture and Lifecycle
The Preview Server UI runs as a Next.js application managed by the React Email CLI. When you run the email dev command, the CLI initializes an HTTP server that serves the UI and processes template files for previewing.
Development Server Startup
The startDevServer function initializes the preview environment. It resolves the location of the UI package, sets up an HTTP server, and prepares the Next.js application.
The diagram shows the initialization sequence from the CLI command to the active listening state of the preview server.
Sources: packages/react-email/src/cli/utils/preview/start-dev-server.ts:40-155
Request Handling Logic
The server handles two primary types of requests:
- Static Files: Requests to
static/(excluding_next/static/) serve local image assets from the user's emails directory. - Template Previews: Dynamic routes resolve file slugs to absolute paths to render the React components.
Sources: packages/react-email/src/cli/utils/preview/start-dev-server.ts:70-98, packages/ui/src/app/preview/[...slug]/page.tsx:44-55
Template Rendering and Data Flow
The Preview page acts as the main orchestrator for rendering a specific email template. It performs several asynchronous operations to gather metadata and validation results before displaying the content.
Rendering Process
The UI performs the following steps when a user selects a template:
- Slug Resolution: The system converts the URL slug into an absolute filesystem path.
- Email Rendering: The
renderEmailByPathfunction produces the HTML markup, plain text version, and React source. - Metadata Extraction: The server retrieves directory metadata to populate the navigation sidebar.
- Static Build Checks: If the app is in a building state, it executes intensive linting and compatibility checks.
Sources: packages/ui/src/app/preview/[...slug]/page.tsx:44-77
Data Flow for Preview Page
| Action | Component/Function | Description |
|---|---|---|
| Path Resolution | getEmailPathFromSlug | Maps URL segments to the physical .tsx or .html file. |
| Core Rendering | renderEmailByPath | Generates prettyMarkup, reactMarkup, and plainText. |
| Directory Metadata | getEmailsDirectoryMetadata | Scans the emails directory to build the file tree. |
| Provider Setup | PreviewProvider | Wraps the UI in a context containing the rendering results and slug. |
Sources: packages/ui/src/app/preview/[...slug]/page.tsx:37-142
Quality Assurance and Insights
The Preview Server UI includes a Toolbar that provides diagnostic information about the current email template.
Validation Services
The UI integrates multiple validation streams to ensure email quality:
- Linting: Analyzes the generated HTML for syntax errors and best practices.
- Compatibility: Checks React/JSX code against a database of email client support (Gmail, Outlook, Apple Mail, Yahoo).
- Spam Check: Sends the HTML and plain text to
https://react.email/api/check-spamto retrieve a spam score.
The sequence diagram illustrates how the server performs rendering and validation in parallel before delivering results to the client.
Sources: packages/ui/src/app/preview/[...slug]/page.tsx:79-130
Interactive Tools
The Preview Server UI provides interactive components to assist in template development and testing.
Preview Props Editor
The PreviewPropsEditor allows you to live-edit the data passed to email components. It uses a syntax-highlighted JsonEditor and applies changes using a debounced callback to prevent excessive re-renders.
- Reset Logic: A "Reset to defaults" button clears overrides and restores the template's defined
PreviewProps. - Validation: The editor flags invalid JSON objects and displays parse errors inline.
- Read-only Mode: When viewing a static build, the editor becomes read-only.
Sources: packages/ui/src/components/preview-props-editor.tsx:10-75, packages/ui/CHANGELOG.md:43-52
Navigation and Viewport Control
- Sidebar: Maintains scroll position and collapsed folder states across template navigations.
- Toolbar: Provides tabs for switching between the visual preview, raw HTML view, and plain text view.
- Responsive Viewport: The preview frame can be resized to test mobile and desktop layouts.
Sources: packages/ui/CHANGELOG.md:32-34, packages/ui/CHANGELOG.md:143-145, packages/ui/src/app/preview/[...slug]/page.tsx:143-157
CLI Configuration and Deployment
The preview environment is configurable via CLI flags and environment variables.
| Configuration Option | Description | Source |
|---|---|---|
--dir | Specifies the directory containing email templates. | SKILL.md:310 |
--port | Sets the port for the development server (default 3000). | SKILL.md:310 |
--clients | Narrows which email clients trigger compatibility warnings. | packages/ui/CHANGELOG.md:104-110 |
--esbuild-plugins | Passes custom plugins for compile-time transforms. | packages/ui/CHANGELOG.md:15-18 |
Sources: SKILL.md:310-320, packages/ui/CHANGELOG.md:15-110
Summary
The Preview Server UI serves as a centralized hub for React Email development. By combining live rendering, a dynamic props editor, and deep integration with quality assurance tools like spam checking and client compatibility matrices, it enables developers to build robust emails that perform consistently across different email clients.