npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

handlebars-email-renderer

v2.0.2

Published

Allows you to create components that render to email HTML using Handlebars.js.

Downloads

3

Readme

HandlebarsEmailRenderer

npm version License GitHub repo size TypeScript js-standard-style

GitHub issues GitHub pull requests GitHub last commit

Installation

To install the package, run the following command:

npm install handlebars-email-renderer

# or

yarn add handlebars-email-renderer

Usage

This view engine uses the architecture of the 'views' folder to structure the different views of emails. This makes it trivial to use in basic applications, but you must ensure that this folder has at least the following architecture:

Basic Usage

In this section, we will cover the basic usage of HandlebarsEmailRenderer. We will show you how to create a simple email using the default layout and a single view.

Directory Structure:

To get started, you'll need to create a views directory with the following structure:

.
├── views
│   ├── layouts
│   │   └── main.hbs
│   └── welcome.hbs

2 directories, 2 files

The layouts folder contains the different layouts that can be used to structure your emails. For this example, we only need one layout, which we'll call main.hbs. This layout defines the basic structure of the email.

The welcome.hbs file is the view that will be rendered as the body of the email. This file contains the content that will be sent to the user.

Code Explanation:

To use HandlebarsEmailRenderer in your project, you'll need to create an instance of the HandlebarsEmailRenderer class with the desired options:

const { HandlebarsEmailRenderer } = require("handlebars-email-renderer");

const renderer = new HandlebarsEmailRenderer();

// You can customize the path and name of the `views` directory by passing a `viewsPath` option when instantiating the module:

const renderer = new HandlebarsEmailRenderer({
  viewsPath: "./my-email-templates",
});

The render method is used to render the email template. By default, the method will look for a view with the same name as the first argument passed to the function in the views directory. In this example, the welcome.hbs view will be rendered with the main.hbs layout:

const email = await renderer.render("welcome");
// or synchronous method
const email = renderer.renderSync("welcome");

Warning: Using the renderSync method is discouraged, as it may crash the Node.js process and cause performance issues. Use it only if you are certain that performing this method will not impact the performance of your application.

The email variable will now contain the rendered HTML email.

views/layouts/main.hbs:

The main layout is the HTML page wrapper which can be reused for the different views of the mail. {{{body}}} is used as a placeholder for where the main content should be rendered.

<html>
  <head>
    <meta charset="utf-8" />
    <title>Example Email</title>
  </head>
  <body>
    {{{body}}}
  </body>
</html>

views/welcome.hbs:

The content for the mail welcome which will be rendered into the layout's {{{body}}}.

<h1>Welcome, new user!</h1>

Advenced Usage

In this part, we introduce to choose a custom layout and use personalized data inside your emails. We will also see how the partials which allow you to break down your code into smaller portions of reusable components in all your emails. Before going further we recommend that you read the documentation handlebars introduction

Custom Layout:

To use a layout other than the default (main.hbs), you must pass the layout argument with the name of the corresponding .hbs file in the layouts directory.

// For use 'views/layouts/admin.hbs'

const email = await renderer.render("welcome", {
  layout: "admin",
});

Expressions:

You can pass custom data to your email on the second argument of the render method:

const email = await renderer.render("welcome", {
  user: {
    firstName: "John",
    pets: [
      {
        name: "Beethoven",
        dog: true,
      },
      {
        name: "Garfield",
        dog: false,
      },
    ],
  },
});

You can pass data in the following way into layouts and partials:

<!-- views/welcome.hbs: -->

<h1>Welcome, {{user.firstName}}</h1>

Yous can use some expression that is part of the Handlebars language itself:

<!-- views/welcome.hbs: -->

<h1>Welcome, {{user.firstName}}</h1>
{{#each user.pets}}
  <p>
    Your pet is named
    {{user.pets.name}}
    {{#if user.pets.dog}}
      , it is a dog!
    {{/if}}
  </p>
{{/each}}

Helpers can be used to implement functionality that is not part of the Handlebars language itself A helper can be registered at runtime via Handlebars.registerHelper, for example in order to uppercase all characters of a string.

const renderer = new HandlebarsEmailRenderer({
  helpers: {
    toUppercase: (text) => {
      return text.toUpperCase();
    },
  },
});
<!-- views/welcome.hbs: -->

<h1>Welcome, {{toUppercase user.firstName}}</h1>

for more information on expressions, see handlbars expressions.

Partials:

Directory Structure:

# With partials and subfolder of partials
.
├── views
│   ├── layouts
│   │   └── main.hbs
│   ├── partials
│   │   ├── components
│   │   │   └── button.hbs
│   │   ├── end.hbs
│   │   ├── head.hbs
│   │   └── navbar.hbs
│   └── welcome.hbs

4 directories, 6 files

In this architecture, we add:

  • a partials folder to organize the different components to reuse in your layouts and/or in your views.
  • one or more partials subfolders, to help structure your components.
  • several *.hbs files containing your components (one file = one partial).

For use a partial on layout (or on view):

<!-- views/layout/main.hbs: -->
{{> head }}

{{{ body }}}

{{> end }}
<!-- views/partials/head.hbs: -->
<html>
  <head>
    <meta charset="utf-8" />
    <title>Example Email</title>
  </head>
  <body>
<!-- views/partials/end.hbs: -->
  </body>
</html>

You can pass data to your component (partial) in the following way:

<!-- views/welcome.hbs: -->

<h1>Welcome, user</h1>
{{> components/button text='Click here!' link='https://github.com/handlebars-email-renderer/handlebars-email-renderer'}}
<!-- views/partials/components/button.hbs: -->

<a href="{{link}}">{{text}}</a>

for more information on partials, see handlbars partials.

More:

For more information on advanced handlebars features read handlebars documentation.

For more information on how to use HandlebarsEmailRenderer, please refer to the API documentation.

Contributing

Contributions are welcome! If you find a bug or want to suggest a new feature, please open an issue on the GitHub repository.

Before submitting a pull request, please make sure that your changes are consistent with the code style of the project, and that all tests pass. To run the tests, use the following command:

npm test

Acknowledgments

We would like to thank the team who created and maintains the Handlebars.js package on which this module is entirely based. We also express our gratitude to the contributors of Express Handlebars who have greatly inspired this module and have been a great help to us in many projects.

License

HandlebarsEmailRenderer is licensed under the MIT License.

Donation

If you have found my work useful and would like to support me, you can donate via PayPal or Bitcoin. Thank you in advance for your support!

PayPal

paypal

Bitcoin

bitcoin

1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2