BP Email Base

React-based email components to reliably build HTML emails that work across major email clients

This package provides a comprehensive set of React components specifically designed for building HTML emails that render consistently across all major email clients, including Outlook, Gmail, Apple Mail, and more. Built with TypeScript and optimized for email client compatibility.

🚀 Features

• Cross-Client Compatibility: Components are built using table-based layouts and inline styles to ensure consistent rendering across all email clients
• React-Based: Leverage the power of React for component composition and reusability
• TypeScript Support: Full TypeScript definitions for better development experience and type safety
• Email-Specific Components: Purpose-built components for common email patterns (containers, sections, columns, buttons, etc.)
• VML Support: Built-in support for Vector Markup Language (VML) for Outlook compatibility
• Raw HTML Injection: Safe raw HTML injection for complex email layouts
• Responsive Design: Mobile-friendly components that adapt to different screen sizes
• MSO Support: Microsoft Outlook-specific styling and conditional comments

📦 Installation

Prerequisites

• Node.js (16.0 or greater)
• npm or yarn
• React 18.2.0 or greater (peer dependency)

Install the Package

npm install @hilemangroup/bp-email-base

or

yarn add @hilemangroup/bp-email-base

🏗️ Core Components

Layout Components

• Container - Main email container with configurable width and gutters
• Section - Full-width sections with background colors and padding
• Column - Flexible column layouts for responsive email design
• Wrap - Wrapper component for grouping content

Content Components

• RichText - Styled text content with email-safe formatting
• ImageBlock - Responsive images with proper email client support
• Button - Email-safe buttons that work across all clients
• BackgroundSection - Sections with background images (with VML fallbacks)

Utility Components

• Raw - Safe injection of raw HTML content
• ConditionalComment - Outlook-specific conditional comments
• Element - Generic HTML element wrapper with email-safe attributes

🎯 Usage

Basic Email Structure

import React from 'react';
import { Container, Section, Column, RichText, Button } from '@hilemangroup/bp-email-base';

const MyEmail = () => {
  return (
    <Container width="600px">
      <Section backgroundColor="#f8f9fa" padding="20px">
        <Column>
          <RichText>
            <h1>Welcome to Our Newsletter!</h1>
            <p>Thank you for subscribing to our updates.</p>
          </RichText>
          <Button href="https://example.com" backgroundColor="#007bff">
            Learn More
          </Button>
        </Column>
      </Section>
    </Container>
  );
};

Multi-Column Layout

import React from 'react';
import { Container, Section, Column, RichText, ImageBlock } from '@hilemangroup/bp-email-base';

const TwoColumnEmail = () => {
  return (
    <Container width="600px">
      <Section padding="20px">
        <Column width={6}>
          <ImageBlock 
            src="https://example.com/image1.jpg" 
            alt="Product Image"
            width="250"
          />
        </Column>
        <Column width={6}>
          <RichText>
            <h2>Our Latest Product</h2>
            <p>Discover amazing features and benefits.</p>
          </RichText>
        </Column>
      </Section>
    </Container>
  );
};

Using Raw HTML

import React from 'react';
import { Container, Raw } from '@hilemangroup/bp-email-base';

const CustomEmail = () => {
  return (
    <Container>
      <Raw text="<!--[if mso]><xml>Custom Outlook content</xml><![endif]-->" />
      {/* Your other components */}
    </Container>
  );
};

🛠️ Build Process

The package includes a build utility to process your React email components into email-ready HTML:

import { replaceRawTags } from '@hilemangroup/bp-email-base';

// After rendering your React email to HTML string
const processedHtml = replaceRawTags(htmlString);

🎨 Styling

CSS-in-JS Support

Components support both inline styles and CSS-in-JS patterns:

<Section 
  style={{ backgroundColor: '#f0f0f0' }}
  padding="20px 10px"
>
  <RichText style={{ color: '#333', fontSize: '16px' }}>
    Styled content
  </RichText>
</Section>

MSO-Specific Styles

The package includes TypeScript definitions for Microsoft Outlook-specific CSS properties:

<div style={{
  'mso-line-height-rule': 'exactly',
  'mso-text-raise': '2px'
}}>
  Outlook-optimized content
</div>

🧪 Development

Setting Up Development Environment

# Clone the repository
git clone <repository-url>
cd bp-email-base

# Install dependencies
npm install

# Start development server
npm start

# Build for production
npm run build

Project Structure

src/
├── js/
│   ├── components/        # React email components
│   ├── util/             # Utility functions
│   ├── build/            # Build-time utilities
│   ├── constants/        # Email constants and aliases
│   ├── vml/              # VML type definitions
│   └── types.ts          # TypeScript type definitions

📚 API Reference

Component Props

All components extend base LayoutProps:

interface LayoutProps {
  children?: ReactNode;
  varName?: string;
  className?: string;
  innerClassName?: string;
  style?: CSSProperties;
  innerStyle?: CSSProperties;
}

Utility Functions

• replaceRawTags(html: string): string - Remove raw HTML tags from processed email
• getColumnInnerWidth(width: string, gutter: number): number - Calculate inner column widths
• cssModifier(base: string, modifier?: string): string - Generate BEM-style class names
• parseCssSideValues(value: CssSidesValues): object - Parse CSS shorthand values

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.