BootstrapEmail.Net 2.0.0

BootstrapEmail.NET

If you know Bootstrap, you know Bootstrap Email.

BootstrapEmail.NET is the .NET version of Bootstrap Email, converted from Ruby. Write emails with the Bootstrap classes you already know, and it compiles them into the table-based HTML with inline styles that email clients need.

For example, this button:

<a href="https://example.com" class="btn btn-primary">Confirm</a>

compiles to this (some styles shortened):

<table class="btn btn-primary" role="presentation" border="0" cellpadding="0" cellspacing="0" style="border-radius: 6px; ...">
  <tbody>
    <tr>
      <td align="center" bgcolor="#0d6efd" style="border-radius: 6px; ...">
        <a href="https://example.com" style="background-color: #0D6EFD; color: #FFFFFF; ...">Confirm</a>
      </td>
    </tr>
  </tbody>
</table>

See the Bootstrap Email documentation for the available components and utilities.

Contents

• Requirements
• Use the library
• Use the command line
• Configuration
• Custom styles
• Files created at runtime
• Upgrading to 2.0
• Development
• License

Requirements

• .NET 9 or .NET 10
• Any operating system supported by .NET. No Dart Sass binary or other native runtime is needed.

Use the library

Install the package:

dotnet add package BootstrapEmail.Net

Compile a string and get the HTML back:

using BootstrapEmail.Net;

var bsEmail = new BootstrapEmailCompiler();

var html = bsEmail.Compile(
    "<a href='#' class='btn btn-primary'>Some Button</a>",
    string.Empty,
    InputType.String);

The other input types write to files and return an empty string:

// Compile email.html and save it to out.html
bsEmail.Compile("email.html", "out.html", InputType.File);

// Compile email.html and save it to compiled/email.html
bsEmail.Compile("email.html", string.Empty, InputType.File);

// Compile all .html files in the current directory and save them to compiled/
bsEmail.Compile(string.Empty, string.Empty, InputType.File);

// Compile the files matching a pattern and save them to a directory
bsEmail.Compile("emails/*", "emails/compiled", InputType.Pattern);

To change the defaults, pass a ConfigStore:

var bsEmail = new BootstrapEmailCompiler(new ConfigStore { CompileOnlyBody = true });

Use the command line

The CLI is a .NET tool that installs the bootstrap-email command:

dotnet tool install --global BootstrapEmail.Net.Cli

To update it, run dotnet tool update --global BootstrapEmail.Net.Cli.

Without any input option, it compiles the HTML piped to it and writes the result to the console. If nothing is piped, it compiles all .html files in the current directory and saves them to compiled/:

cat input.html | bootstrap-email
bootstrap-email

Compile one file:

bootstrap-email -f email.html -d out.html

Compile the files matching a pattern. Quote the pattern so that your shell doesn't expand it:

bootstrap-email -p 'emails/*' -d emails/compiled

Compile a string:

bootstrap-email -s '<a href="#" class="btn btn-primary">Some Button</a>'

Save the plain text version of an email:

bootstrap-email -t -f email.html -d email.txt

Use a configuration file:

bootstrap-email -c bootstrap-email.json -f email.html

Configuration

The library takes these settings as ConfigStore properties, and the CLI reads them from a JSON file with the same names:

{
  "sass_email_location": "styles",
  "sass_email_string": "my-email.scss",
  "sass_log_enabled": true
}

Custom styles

The default stylesheets are included precompiled, so compiling an email normally doesn't run Sass at all. There are two ways to customize them:

• Use your own Sass file. Copy core/bootstrap-email.scss (see Files created at runtime), add your styles, and point sass_email_location and sass_email_string at the copy. You can also edit the files in core/ directly.
• Use your own CSS file. Set CssEmailPath or CssHeadPath. The file replaces the Bootstrap Email styles instead of adding to them, and no Sass is compiled.

Custom Sass is compiled in managed code with DartSassHost and Jint. The first compile takes several seconds, and the result is cached until the Sass files change. To clear the cache, call ClearSassCache().

Files created at runtime

Bootstrap Email creates these in the current directory, which therefore has to be writable:

Upgrading to 2.0

• Rename BootstrapEmail to BootstrapEmailCompiler.
• Remove any DartSass.Native.* package references. Sass is now compiled in managed code, so the Dart Sass runtime is no longer needed.
• Remove ConfigStore.DartSassNativeType. There is no replacement, because no runtime has to be selected.
• StyleType is now BootstrapEmail.Net.StyleType, instead of the type from Citizen17.DartSass.
• The CLI option --text no longer takes a value.
• plain_text now also applies to file and pattern input, not just strings.
• Pattern input now compiles the content of the matching files. Earlier versions compiled the file path by mistake.

Development

dotnet test BootstrapEmail.Net.slnx

The precompiled CSS in BootstrapEmailNet/precompiled/ has to match the core Sass files, and a test fails if it doesn't. After changing the Sass files or updating DartSassHost, regenerate the CSS and rebuild:

BOOTSTRAP_EMAIL_UPDATE_PRECOMPILED=1 dotnet test BootstrapEmailNet.Tests/BootstrapEmail.Net.Tests.csproj -f net10.0 --filter "FullyQualifiedName~PrecompiledCssMatchesCoreSass"

In PowerShell, set the variable first with $env:BOOTSTRAP_EMAIL_UPDATE_PRECOMPILED = 1.

License

MIT