Local Dev Server (email dev)
Relevant source files
The following files were used as context for generating this wiki page:
The Local Dev Server provides a real-time preview environment for developing HTML email templates using React. It starts a local web server that watches the filesystem, bundles email components, and renders a visual interface for testing templates across different configurations and simulated email clients.
The server runs by default at localhost:3000 and serves a preview interface for all templates found in the specified emails directory. It utilizes esbuild for rapid bundling of TypeScript/React files and a Next.js-based UI (found in @react-email/ui) to display the rendered output.
Sources: SKILL.md:46-51, README.md:23-28, packages/react-email/readme.md:20-22
CLI Configuration and Commands
You interact with the development server primarily through the email dev command. This command initializes the watcher and the preview server.
Available Flags
| Flag | Description | Default |
|---|---|---|
--dir <path> | Sets the directory containing email templates. | ./emails |
--port <port> | Defines the port for the preview server. | 3000 |
--esbuild-plugins <path> | Path to a module exporting custom esbuild plugins for transforms. | N/A |
--clients <list> | Narrows compatibility warnings to specific clients (e.g., gmail,outlook). | gmail,apple-mail,outlook,yahoo |
Sources: SKILL.md:255-262, packages/react-email/readme.md:24-30, packages/ui/CHANGELOG.md:120-125
Development Workflow
The diagram shows the iterative cycle where the CLI watches for local changes, triggers a bundle via esbuild, and updates the UI.
Sources: packages/react-email/readme.md:20-22, packages/ui/CHANGELOG.md:88-92
Preview UI and Features
The development server includes a specialized UI, formerly known as @react-email/preview-server and now named @react-email/ui. This interface provides tools to inspect and validate email templates.
Core UI Components
- Sidebar: Displays the file tree of the emails directory, maintaining scroll position and folder state across template navigation.
- Props Editor: A collapsible panel containing a syntax-highlighted JSON editor for live-editing the props passed to the email component.
- Dark Mode Switcher: A tool that emulates email client color inversion to test how templates appear in dark mode.
- Compatibility Insights: Displays warnings for CSS properties or HTML elements not supported by major email clients like Gmail or Outlook.
Sources: packages/ui/CHANGELOG.md:42-45, packages/ui/CHANGELOG.md:55-58, packages/ui/CHANGELOG.md:162-163, packages/ui/CHANGELOG.md:203-205
Hot Reloading Mechanism
The dev server implements a socket-based hot reloading system to ensure the preview stays in sync with the source code.
The sequence diagram illustrates how a file save triggers a cache invalidation and a socket message to the UI for immediate re-rendering.
Sources: packages/ui/CHANGELOG.md:52-54, packages/ui/CHANGELOG.md:88-92
Hot reloading is optimized to prevent out-of-memory crashes by re-rendering only the open preview and invalidating the cache for other affected templates rather than re-rendering every dependent file.
Sources: packages/ui/CHANGELOG.md:88-92
Static Asset Serving
The dev server handles static assets (images) through a specific directory structure.
- Place images in the
staticfolder inside the emails directory (e.g.,emails/static/logo.png). - The server serves these assets at the
/static/path. - The
baseURLpattern is used to differentiate between local development and production CDNs.
const baseURL = process.env.NODE_ENV === "production"
? "https://cdn.example.com"
: "";
// In development, this resolves to "/static/logo.png"
<Img src={`${baseURL}/static/logo.png`} />
Sources: SKILL.md:144-159, SKILL.md:170-174, skills/react-email/TESTS.md:255-265
Compatibility and Validation
The server performs automated checks to identify potential rendering issues in email clients.
- CSS Normalization: The server resolves CSS variables and normalizes RGB color syntax for compatibility.
- Tailwind Integration: When using the
Tailwindcomponent, the server automatically converts classes to inline styles and extracts media queries to a<style>tag in the<head>. - Diagnostics: The system reports line and column numbers for validation errors, including fixes for CRLF line endings on Windows.
Sources: SKILL.md:201-208, packages/ui/CHANGELOG.md:108-112, packages/ui/CHANGELOG.md:197-200
The Local Dev Server is the central tool for the React Email workflow, combining esbuild's performance with a feature-rich UI to bridge the gap between React component development and archaic email client rendering engines.