Modern Template Consolidation Engine for EJS, Markdown, Pug, Nunjucks, Mustache, and Handlebars

---

Ecto is a modern template consolidation engine that enables the best template engines: EJS, Markdown, Pug, Nunjucks, Mustache, Handlebars, and Liquid. It consolidates these template engines to a single library, allowing you to use any of them with ease.

Features

• Zero Config by default but all properties exposed for flexibility. Check out our easy API.
• Async render and renderFromFile functions for ES6 and Typescript.
• Render via Template File with Automatic Engine Selection. No more selecting which engine to use, engine choice is automatically decided based on the file extension.
• Only the Top Template Engines: EJS, Markdown, Pug, Nunjucks, Mustache, Liquid, and Handlebars.
• FrontMatter Helpers .hasFrontMatter, .getFrontMatter, and .removeFrontMatter for Markdown files.
• Maintained with Monthly Updates!

Table of Contents

• Getting Started
• Only the Top Template Engines and Their Extensions
• API - Methods and Parameters
  • Render From String
  • Render From File
  • Default Engine
  • Engine Mappings
  • FrontMatter Helper Functions
  • Detect Template Engine
• The Template Engines We Support
  • EJS
  • Markdown
  • PUG
  • Nunjucks
  • Mustache
  • Handlebars
  • Liquid
• FrontMatter Helper Functions
• Caching on Rendering
• Emitting Events
• Hooks
• Creating Custom Engines
  • Direct Engine Usage
  • Creating a Custom Engine
  • Integrating Custom Engine with Ecto
  • Engine Interface Reference
  • BaseEngine Helper Methods
  • Tips for Custom Engines
• How to Contribute
• License

Getting Started

The Node.js package manager documentation provides the commands needed to complete the install on Windows and other operating systems.

1. Open the terminal for your project and run npm install to ensure all project dependencies are correctly installed.

npm install ecto

2. Declare and Initialize.

import { Ecto } from `ecto`;

const ecto = new Ecto();

5. Render via String for EJS (Default Engine)

const source = "<h1>Hello <%= firstName%> <%= lastName %>!</h1>";
const data = {firstName: "John", lastName: "Doe"}
ecto.render(source, data).then((output) => {
    console.log(output);
});

After running your program you should see the following output:

<h1>Hello John Doe!</h1>

---

You can easily set a different defaultEngine, here we use Handlebars.

import { Ecto } from `ecto`;
const ecto = new Ecto({defaultEngine: "handlebars"});

let source = "<h1>Hello {{ firstName }} {{ lastName }}!</h1>";
let data = {firstName: "John", lastName: "Doe"};
await ecto.render(source, data); //returns <h1>Hello John Doe!</h1>

To render from a template file, Ecto uses the renderFromFile function. This performs an automatic selection of the engine based on the file extension.

import { Ecto } from `ecto`;
const ecto = new Ecto();
let data = { firstName: "John", lastName: "Doe"};
//async renderFromFile(filePath:string, data?:object, rootTemplatePath?:string, filePathOutput?:string, engineName?:string): Promise<string>
await ecto.renderFromFile("./path/to/template.ejs", data); // returns <h1>Hello John Doe!</h1>

Only the Top Template Engines and Their Extensions

We focus on the most popular and well-maintained consolidation engines. Unfortunately other engines suffered from packages that were unsupported, making it difficult to validate them as working fully. Some engines also had limited types and lacked ease of use.

Our goal is to support the top engines, handling the vast majority of use cases. Here are the top engines that we support:

| Engine | Monthly Downloads | Extensions | | ---------- | ---------------------------------------------------------------------------------------------- | ----------------------- | | EJS | | .ejs | | Markdown | | .markdown, .md | | Pug | | .pug, .jade | | Nunjucks | | .njk | | Mustache | | .mustache | | Handlebars | | .handlebars, .hbs, .hjs | | Liquid | | .liquid | |

The Extensions are listed above for when we Render from File.

API - Methods and Parameters

The API is focused on using the main Ecto class:

const ecto = new Ecto();
//ecto.<API> -- functions and parameters

There are a couple of options that can be passed to the Ecto constructor:

| Name | Type | Description | | ---------------- | ------ | ------------------------------------------------------------ | | defaultEngine | string | This is the default engine to use if it is not set when doing rendering | | engineOptions | object | The options for each engin that you can set initially. |

here is an example of setting the default engine and also options for nunjucks:

const ecto = new Ecto({defaultEngine: "nunjucks", engineOptions: {nunjucks: {autoescape: true}});

When looking at the API there are two main methods to make note of: render (async) - Render from a string. renderFromFile (async) - Renders from a file path and will auto-select what engine to use based on the file extension. It will return a Promise<string> of the rendered output.

Render From String

As we have shown in Getting Started -- It's that Easy! You can render in only a couple of lines of code.

render and renderSync (async) - Render from a string. Here is the render function with all possible arguments shown:

| Name | Type | Description | | ---------------- | ------ | ------------------------------------------------------------ | | source | string | The markup/template source to be rendered. | | data | object | The data to be rendered by the file. | | engineName | string | Used to override the Ecto.defaultEngine parameter. | | rootTemplatePath | string | The root template path that is used for partials and layouts. | | filePathOutput | string | Used to specify the file path, if you want to write the rendered output to a file. |

Here is the simplest example of a render function. We are also showing the required steps you need to take beforehand such as setting up Ecto.

const ecto = new Ecto();

const source = "<h1>Hello <%= firstName%> <%= lastName %>!</h1>";
const data = {firstName: "John", lastName: "Doe"};
await ecto.render(source, data); //returns <h1>Hello John Doe!</h1>

If you want to do synchronous rendering, you can do so by using the renderSync function. This function takes the same parameters as the render function.

const ecto = new Ecto();
const source = "<h1>Hello <%= firstName%> <%= lastName %>!</h1>";
const data = {firstName: "John", lastName: "Doe"};
ecto.renderSync(source, data); //returns <h1>Hello John Doe!</h1>

Now let's say your desired engine is not EJS, you will need to specify it explicitly. You can either set the defaultEngine parameter, or simply pass it in the render function. In this case with the popular engine, [Handlebars](https://www.np