Oy

Emails, oy vey!

Render HTML emails on the server with React. Oy provides functionality to:

Validate props against email best-practices with Oy components.
Render templates server-side with Oy.renderTemplate.

Blog Post - ReactConf 2016 talk

NOTE: If using TypeScript, the current typings result in quickly growing compilation times. I would suggest not using TypeScript with Oy until the bug is addressed. If TypeScript is a requirement, see a workaround that disables a subset of type-checks.

Installation

npm install --save oy-vey

Example usage

Replace table markup with validating Oy components

import React from 'react';
import Oy from 'oy-vey';

const {Table, TBody, TR, TD} = Oy;

export default (props) => {
  return (
    <Table width={props.maxWidth}>
      <TBody>
        <TR>
          <TD align="center">
            {props.children}
          </TD>
        </TR>
      </TBody>
    </Table>
  );
};

Compose higher level components like usual

import React from 'react';

import MyLayout from './layout/MyLayout.jsx';
import BodyText from './modules/BodyText.jsx';

export default (props) => {
  return (
    <MyLayout>
      <BodyText>Welcome to Oy!</BodyText>
    </MyLayout>
  );
};

Inject rendered code into HTML skeleton with Oy.renderTemplate

For example, if using Express.js:

import express from 'express';
import React from 'react';
import Oy from 'oy-vey';

import GettingStartedEmail from './templates/GettingStartedEmail.jsx';

const server = express();
server.set('port', (process.env.PORT || 8887));

server.get('/email/oy', (req, res) => {
  const template = Oy.renderTemplate(<GettingStartedEmail />, {
    title: 'Getting Started with Foo',
    headCSS: '@media ...',
    previewText: 'Here is your guide...'
  });
  res.send(template);
});

server.listen(server.get('port'), () => {
  console.log('Node server is running on port', server.get('port'));
});

Default components

The Oy namespace exposes the following components validated against email best practices:

Table TBody TR TD Img A

HTML attributes

As of React 16, React will not strip non-standard HTML attributes. That means you can use all the attributes typically required for email templates:

align background bgcolor border valign

For those migrating from previous Oy versions, note that bgColor is now bgcolor and vAlign is valign.

Oy.renderTemplate API

Oy.renderTemplate(<Template />, templateOptions[, generateCustomTemplate])

The templateOptions parameter is an object with the following fields:

title (string, required) - Used by clients if email is opened in a web page.
previewText (string, required) - Short description that appears in email clients
headCSS (string, optional) - CSS that belongs in `<head>`. Note, email clients may strip this out.
bgColor (string, optional) - The background color for the email. '#FFFFFF' is the default
lang (string, optional) - ISO language code
dir (string, optional) - Either 'ltr' or 'rtl'. 'ltr' is the default

Using a Custom Template

If Oy's default template doesn't work for you, you can make your own. generateCustomTemplate takes in templateOptions with an additional property bodyContent, which is the rendered body HTML to be inserted into your template. It then returns a string that should be the final email HTML sent to users.

const generateCustomTemplate = (templateOptions) => {
  return `
    <!doctype html>
    <html>
      <head>
        <title>${templateOptions.title}</title>
      </head>
      <body>
        ${templateOptions.bodyContent}
      </body>
    </html>
  `
};

const template = Oy.renderTemplate(<GettingStartedEmail />, {
  title: 'Getting Started with Foo'
}, (templateOptions) => generateCustomTemplate(templateOptions));

Contributing

# Test
npm test

# Compile from ES6 in src/ to ES5 in lib/
npm run compile

We welcome contributions. If there's some information missing or ideas for how to make Oy better, please send a pull request, file an issue, or email 1.vivekpatel@gmail.com.

The best place to start would be in contributing new rules. A running wishlist of email validation rules are in the Issues section.

revivek / oy

readme

Oy