Handling Static Assets

Relevant source files

The following files were used as context for generating this wiki page:

• skills/react-email/SKILL.md
• README.md
• skills/react-email/TESTS.md
• skills/react-email/references/COMPONENTS.md
• skills/react-email/references/STYLING.md
• apps/demo/emails/03-Protocol/feature-announcement.tsx

Handling static assets within React Email involves managing local storage, environment-specific URL resolution, and cross-client compatibility for images and fonts. The system ensures that assets render correctly in both local development previews and production email environments.

Proper asset management is crucial because email clients require absolute URLs to fetch external content. React Email provides a structured directory pattern and a conditional URL resolution strategy to bridge the gap between local development and hosted production environments.

Directory Structure and Storage

React Email requires a specific folder structure to serve local assets during development. You must place all local images and static files in a static folder located within your emails directory.

Sources: SKILL.md:162-171, TESTS.md:195-207

project/
├── emails/
│   ├── welcome.tsx
│   └── static/           <-- Place all images here
│       └── logo.png

Sources: SKILL.md:164-169

The React Email development server automatically serves files from this directory. If assets exist in other project folders, you must copy them to the emails/static/ directory to make them accessible to the preview tool.

Sources: TESTS.md:200-202

Environment-Based URL Management

Email clients cannot resolve relative paths like ./static/logo.png. You must use absolute URLs for all assets. React Email utilizes a baseURL pattern to toggle between the local development server and a production Content Delivery Network (CDN).

URL Resolution Logic

The application checks the NODE_ENV variable to determine which base path to apply to asset requests.

The diagram shows how the system resolves asset locations based on the environment setting.

Sources: SKILL.md:173-181, TESTS.md:213-228

Implementation Example

Developers implement this logic by defining a baseURL constant at the top of the email template file.

const baseURL = process.env.NODE_ENV === "production"
  ? "https://cdn.example.com"  // Production CDN
  : "";                        // Development local serve

export default function Email() {
  return (
    <Img
      src={`${baseURL}/static/logo.png`}
      alt="Logo"
    />
  );
}

Sources: SKILL.md:173-189, feature-announcement.tsx:23-25

Image Asset Guidelines

Email clients impose strict limitations on image formats and attributes. Following these guidelines ensures consistent rendering across Gmail, Outlook, and mobile clients.

Supported Formats and Constraints

Asset Type	Supported Formats	Prohibited Formats	Rationale
Images	PNG, JPG	SVG, WEBP	SVG/WEBP have unreliable support in Gmail and Outlook.
Alt Text	Descriptive Text	Omitted Attributes	Accessible names are required for screen readers.
Sizing	Fixed or Responsive	Missing Dimensions	Prevents layout shifts and distortion.

Sources: SKILL.md:144, 219, TESTS.md:52-66, 442-463, STYLING.md:46-51, 107-118

Accessibility and Alt Text

You must handle alt attributes based on the image's purpose:

• Meaningful Images: Provide descriptive text explaining the purpose and details.
• Decorative Images: Use an explicit empty string (alt="") so screen readers skip the asset.
• Linked Images: Never use alt="" for images inside links; the text must describe the link destination.

Sources: SKILL.md:364-375, COMPONENTS.md:209-218, STYLING.md:118-132

Component Implementation

The Img component is the primary interface for embedding static assets.

Key Props and Attributes

Prop	Requirement	Description
src	Required	The absolute URL of the image.
alt	Required	Accessibility text (defaults to "").
width	Recommended	Fixed width in pixels.
height	Recommended	Fixed height in pixels.

Sources: COMPONENTS.md:197-221

Best Practices for Images

• Always use absolute URLs.
• Specify width and height to prevent layout shifts.
• Use block classes to remove unwanted whitespace at the bottom of images in some clients.
• Avoid using fixed pixel dimensions for large hero images; use w-full with h-auto instead.

Sources: COMPONENTS.md:219-223, STYLING.md:112-114

Summary

Handling static assets in React Email requires centralizing files in the emails/static/ directory and utilizing environment-specific baseURL logic. By adhering to supported formats (PNG/JPG) and providing proper accessibility attributes, developers ensure templates remain functional and accessible across all major email clients.

Sources: SKILL.md, STYLING.md, COMPONENTS.md