eta (Ξ·)
Documentation -
Chat -
RunKit Demo -
Playground
[logo]: https://img.shields.io/badge/all_contributors-10-orange.svg "Number of contributors on All-Contributors"
[](https://www.npmjs.com/package/eta)
[](https://deno.land/x/eta)
[](https://travis-ci.com/eta-dev/eta)
[![All Contributors][logo]](#contributors-)
[](https://coveralls.io/github/eta-dev/eta)
[](https://paypal.me/bengubler)
**Summary**
Eta is a lightweight and blazing fast embedded JS templating engine that works inside Node, Deno, and the browser. Created by the developers of [Squirrelly](https://squirrelly.js.org), it's written in TypeScript and emphasizes phenomenal performance, configurability, and low bundle size.
### π Features
- π¦ 0 dependencies
- π‘ 2.3KB minzipped; size restricted to <3KB forever with [size-limit](https://github.com/ai/size-limit)
- β‘οΈ Written in TypeScript
- β¨ Deno support (+ Node and browser)
- π Super Fast
- Check out [these benchmarks](https://raw.githack.com/eta-dev/eta/master/browser-tests/benchmark.html)
- π§ Configurable
- Plugins, custom delimiters, caching
- π¨ Powerful
- Precompilation, partials, async
- **Layout support**!
- ExpressJS support out-of-the-box
- π₯ Reliable
- Better quotes/comments support
- _ex._ `<%= someval + "string %>" %>` compiles correctly, while it fails with doT or EJS
- Great error reporting
- β‘οΈ Exports ES Modules as well as UMD
- π Easy template syntax
## Eta vs other template engines
Eta vs EJS
Eta's syntax is very similar to EJS' (most templates should work with either engine), Eta has a similar API, and Eta and EJS share the same file-handling logic. Here are the differences between Eta and EJS:
- Eta is more lightweight. Eta weighs less than **2.5KB gzipped**, while EJS is **4.4KB gzipped**
- Eta compiles and renders templates **_much_ faster than EJS**. Check out these benchmarks: https://rawgit.com/eta-dev/eta/master/browser-tests/benchmark.html
- Eta allows left whitespace control (with `-`), something that doesn't work in EJS because EJS uses `-` on the left side to indicate that the value shouldn't be escaped. Instead, Eta uses `~` to output a raw value
- Eta gives you more flexibility with delimeters -- you could set them to `{{` and `}}`, for example, while with EJS this isn't possible
- Eta adds plugin support
- Comments in Eta use `/* ... */` which allows commenting around template tags
- Eta parses strings correctly. _Example: `<%= "%>" %>` works in Eta, while it breaks in EJS_
- Eta exposes Typescript types and distributes a UMD build
- Eta supports custom tag-type indicators. _Example: you could change `<%=` to `<%*`_
Eta vs doT.js
Eta and doT.js both allow embedded JavaScript, and [both have best-in-class performance](https://ghcdn.rawgit.org/eta-dev/eta/master/browser-tests/benchmark.html) when compared to other template engines (though Eta is slightly faster with HTML-escaped templates). Here are some of the differences between Eta and doT.js:
- Eta allows you to control how you strip preceding and trailing whitespace after tags.
- It's much simpler to set custom delimiters with Eta than doT -- you don't have to rewrite every configuration Regular Expression
- Eta supports plugins
- Eta supports async
- Eta parses strings and multi-line comments correctly. _Example: `<%= "%>" %>` works in Eta, while the equivalent breaks in doT_
- Eta exposes Typescript types and distributes a UMD build
- Eta supports runtime partials and file-handling.
Eta vs Handlebars
Eta and Handlebars are very different in some ways -- Eta is an embedded template engine, while Handlebars is a logic-less template engine. Here some additional differences between Eta and Handlebars:
- Eta is more lightweight. Eta weighs less than **2.5KB gzipped**, while Handlebars is **~22KB gzipped**
- Eta compiles and renders templates **_much_ faster than Handlebars** -- around **7x faster**. Check out these benchmarks: https://ghcdn.rawgit.org/eta-dev/eta/master/browser-tests/benchmark.html
- Eta allows you to set custom delimiters
- Eta supports plugins
- Eta exposes Typescript types and distributes a UMD build
- Custom tag-type indicators. _Example: you could change `<%=` to `<%*`_
- With Eta, you don't need to register tons of helpers to do simple tasks like check if one value equals another value
- Note that Eta templates run as **trusted code** -- just like any other JavaScript you write.
If you are running user-defined/created templates on your machine, server, site, etc., you probably should go with a tool built for that purpose, like Handlebars.
Eta vs ES6 Template Literals
Template literals are a super useful tool, especially for shortening simple string concatenation. But writing complete templates using template literals can quickly get out of hand. Here's a comparison of Eta and template literals:
- Eta compiles templates into JavaScript functions that use string concatenation and have comparable performance with template literals
- Eta lets you control preceding and trailing whitespace around tags
- Eta gives you more flexibility with delimeters -- you could set them to `{{` and `}}`, for example, or set them to `${` and `}` to mimic template literals
- Eta supports plugins
- Eta supports comments with `/* ... */` syntax, just like in regular JavaScript. Template literals require you to stick a blank string after the comment: `/* ... */""`, which is much less readable
- To write conditionals inside template literals, you have to use the ternary operator. Add more conditions or nested conditionals, and it quickly becomes a nightmarish mess of `? ... : ... ? ... : ...`. Writing conditionals in Eta is much simpler and more readable
- Eta supports partials
## Why Eta?
Simply put, Eta is super: super lightweight, super fast, super powerful, and super simple. Like with EJS, you don't have to worry about learning an entire new templating syntax. Just write JavaScript inside your templates.
### Where did Eta's name come from?
"Eta" means tiny in Esperanto. Plus, it can be used as an acronym for all sorts of cool phrases: "ECMAScript Template Awesomeness", "Embedded Templating Alternative", etc....
Additionally, Eta is a letter of the Greek alphabet (it stands for all sorts of cool things in various mathematical fields, including efficiency) and is three letters long (perfect for a file extension).
## Integrations
Visual Studio Code
[@shadowtime2000](https://github.com/shadowtime2000) created [eta-vscode](https://marketplace.visualstudio.com/items?itemName=shadowtime2000.eta-vscode).
ESLint
[eslint-plugin-eta](https://github.com/eta-dev/eslint-plugin-eta) was created to provide an ESLint processor so you can lint your Eta templates.
CLI
An official Eta CLI exists called [etajs-cli](https://github.com/eta-dev/etajs-cli).
Webpack
Currently there is no official Webpack integration but [@clshortfuse](https://github.com/clshortfuse) shared the loader he uses:
```javascript
{
loader: 'html-loader',
options: {
preprocessor(content, loaderContext) {
return eta.render(content, {}, { filename: loaderContext.resourcePath });
},
},
}
```
Node-RED
To operate with Eta templates in Node-RED: [@ralphwetzel/node-red-contrib-eta](https://flows.nodered.org/node/@ralphwetzel/node-red-contrib-eta)
## π Docs
We know nobody reads through the long and boring documentation in the ReadMe anyway, so head over to the documentation website:
π [https://eta.js.org](https://eta.js.org)
## π Examples
### Simple Template
```javascript
import * as Eta from "eta";
var myTemplate = "My favorite kind of cake is: <%= it.favoriteCake %>
";
Eta.render(myTemplate, { favoriteCake: "Chocolate!" });
// Returns: 'My favorite kind of cake is: Chocolate!
'
```
### Conditionals
```ejs
<% if(it.somevalue === 1) { %>
Display this
<% } else { %>
Display this instead
<% } %>
```
### Loops
```ejs
<% it.users.forEach(function(user){ %>
- <%= user.name %>
<% }) %>
```
### Partials
```ejs
<%~ include('mypartial') %>
```
```ejs
<%~ includeFile('./footer') %>
```
```ejs
<%~ include('users', {users: it.users}) %>
```
## βοΈ Tests
Tests can be run with `npm test`. Multiple tests check that parsing, rendering, and compiling return expected results, formatting follows guidelines, and code coverage is at the expected level.
## Resources
To be added
## Projects using `eta`
- [Docusaurus v2](https://v2.docusaurus.io): open-source documentation framework that uses Eta to generate a SSR build
- [swagger-typescript-api](https://github.com/acacode/swagger-typescript-api): Open source typescript api codegenerator from Swagger. Uses Eta as codegenerator by templates
- [html-bundler-webpack-plugin](https://github.com/webdiscus/html-bundler-webpack-plugin): Webpack plugin make easily to bundle HTML pages from templates, source styles and scripts
- [SmartDeno](https://github.com/guildenstern70/SmartDeno): SmartDeno is an easy to setup web template using Deno & Oak
- [Add yours!](https://github.com/eta-dev/eta/edit/master/README.md)
## Contributors
Made with β€ by [@nebrelbug](https://github.com/eta-dev) and all these wonderful contributors ([emoji key](https://github.com/kentcdodds/all-contributors#emoji-key)):
This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind are welcome!
## Credits
- Async support and file handling were added based on code from [EJS](https://github.com/mde/ejs), which is licensed under the Apache-2.0 license. Code was modified and refactored to some extent.
- Syntax and some parts of compilation are heavily based off EJS, Nunjucks, and doT.
