oy-vey
v0.12.1
Published
React utilities for building server-side email templates.
Downloads
52,303
Readme
Oy 
Emails, oy vey!
Render HTML emails on the server with React. Oy provides functionality to:
- Validate props against email best-practices with
Oycomponents. - 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-veyExample 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 AHTML 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 valignFor 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 defaultUsing 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 compileWe 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 [email protected].
The best place to start would be in contributing new rules. A running wishlist of email validation rules are in the Issues section.