akosblazsik / bootstrap-email

Bootstrap Email for NodeJS

If you know Bootstrap, you know Bootstrap Email.

Based on the original Bootstrap Email by stuyam, this library allows you to compile a regular HTML markdown with usual Bootstrap classes into cringy table-based email-layouts ... with JAVASCRIPT 🎉🎊✨.

Table of contents

• Supported Bootstrap Classes
• Additional Classes
• Installation and usage
• Options
• Methods
• Todos
• Known Bugs

Supported Bootstrap Classes

{color} in these examples is primary, secondary, success, warning, danger, light, and dark

• Alerts: .alert, .alert-{color}
• Badges: .badge, .badge-{color}, .badge-pill
• Buttons: .btn, .btn-{color}, .btn-outline-{color}
• Cards: .card, .card-body
• Color: .text-{color}, .bg-{color}
• Containers: .container, .container-fluid
• Floats: .float-left, .float-right
• Grid: .row, .col-{1-12}, .col-lg-{1-12}
• Hrs: <hr>
• Spacing: .p{tlbrxy}-{lg-}{0-5}, .m{tby}-{lg-}{0-5}, mx-auto
• Width: w-{lg-}{25,50,75,100}
• Tables: .table, .table-striped,.table-bordered, .thead-light, .thead-dark, .table-{color}, .table-dark
• Typography: <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <strong>, <u>, <em>, <s>, .text-{sm|lg-}left, .text-{sm|lg-}center, .text-{sm|lg-}right, .display-{1-4}, .lead, .small

Additional Classes

• Visibility: .d-desktop, .d-mobile

Installation and usage

Install package with npm i bootstrap-email -S

To compile a default template:

const BootstrapEmail = require('bootstrap-email');

const template = new BootstrapEmail('<path-to-template>.html');

// const template = new BootstrapEmail([
//     '<path-to-first-template>.html',
//     '<path-to-second-template>.html',
// ]);
//
// const template = new BootstrapEmail('<div class="container">...</div>'); 

template.compileAndSave('<path-to-output>.html');

Alternatively use the Gulp plugin to integrate Bootstrap Email into your templating workflow.

Options

• style string (optional) - Path to css or scss file, which should be inlined. Default is bootstrap-email.scss
• head string (optional) - Path to css or scss file, which should be injected to head. Default is head.scss
• templates array<string> - Array with paths to html files you want to compile.
• logLevel

Methods

new BootstrapEmail(templates, options)

compile(): string | [{path: string, document: string}]

Performs a full compile and returns compiled document(s).

If only one template is about to compile, returns the compiled template, otherwise an array containing objects with the path of the input-file and the compiled document.

const singleTemplate = new BootstrapEmail('<path-to-template>.html');

// returns string
singleTemplate.compile();


const multipleTemplates = new BootstrapEmail(['<path>', ...]);

// returns [{path:'<path-to-source>', document: '...'}, ...]
multipleTemplates.compile();

compileAndSave(path): void

Performs a full compile and saves compiled files into given path.

If only one template is given, pass a full path including filename and extension. Otherwise pass only a directory name. The filenames will be used from the source files.

const singleTemplate = new BootstrapEmail('<path-to-template>.html');
singleTemplate.compileAndSave('./out/compiled.html');


const multipleTemplates = new BootstrapEmail(['<path>', ...]);
multipleTemplates.compileAndSave('./out/');

Todos

• Support multiple CSS/SASS-files
• Add Typescript typings
• Implement bootstrap-like vertical align classes
• Extract automatically CSS that cannot be inlined (:hover, :focus, ...)
• Add option for output formatting (minimized, formatted, ...)
• Write better docs & examples
• Write cli script

Known Bugs

• Outlook 2013 on Windows 10 with 120DPI can't scale images properly
• Paddings don't work properly on Outlook (Windows ofc)
• Auto-sized tables behave as if they would have width="100%" on Outlook 2003 (Windows ofc)
• Outlook 2003 (Windows) is fucked up in general