repository·main·Indexed 23 days ago
https://github.com/bgub/etaA lightweight, high-performance embedded JavaScript templating engine for Node.js, Deno, and the browser. Eta features a small footprint (~3.5 KB minzipped), zero dependencies, and supports both synchronous and asynchronous rendering. It provides a flexible configuration via EtaConfig for interpolation, tags, security filtering, and whitespace control, and includes a robust error reporting system with visual context for parse and runtime errors.
To use Eta, follow these steps:
templates/simple.eta) using Eta's syntax. Variables are accessed via the it object.Eta class in your JavaScript/TypeScript file.Eta instance, optionally providing a views configuration to specify the directory where your templates are located..render() method to compile the template with a data object.You can install Eta using npm to use it in Node, Deno, or the browser environments.
npm install etaEta provides enhanced error messages that include visual context to help you locate exactly where a template failed.
When a parsing error occurs, the error message includes the line number, column number, and a visual pointer (^) to the specific character in the template string that caused the issue.
When a runtime error occurs (such as a ReferenceError inside a template), Eta wraps the original error in an EtaRuntimeError. This error includes:
>>) pointing to the exact line where the error occurred.cause property.While there is no official Webpack integration, you can use html-loader with a custom preprocessor to render Eta templates during the build process.
{
loader: 'html-loader',
options: {
preprocessor(content, loaderContext) {
return eta.render(content, {}, { filename: loaderContext.resourcePath });
},
},
}The EtaConfig interface defines the global configuration for the Eta template engine. You can use these settings to control how templates are parsed, how data is interpolated, and how whitespace is handled.
Key configuration areas include:
tags (default ['<%', '%>']) or specific prefixes for execution (parse.exec), interpolation (parse.interpolate), and raw interpolation (parse.raw).varName (default it) and whether to use the with statement via useWith.autoEscape and automatic filtering with autoFilter. You can provide custom logic via escapeFunction and filterFunction.autoTrim to manage whitespace (options: 'nl', 'slurp', or false) and rmWhitespace to remove empty lines.views and a defaultExtension (default .eta).plugins array, which allows processing template strings, ASTs, or function strings.Use defineConfig from tsdown to specify build configurations for one or more entry points. The configuration accepts an array of objects, allowing you to define different build targets (e.g., Node.js vs. Browser) within the same project.
Available configuration options per entry point:
entry: An array of strings representing the input files.format: An array of output formats (e.g., "esm", "cjs").platform: The target environment (e.g., "node", "browser").dts: Boolean to enable/disable TypeScript declaration generation.sourcemap: Boolean to enable/disable sourcemap generation.minify: Boolean to enable/disable code minification.import { defineConfig } from "tsdown";
export default defineConfig([
{
entry: ["./src/index.ts"],
format: ["esm", "cjs"],
platform: "node",
dts: true,
sourcemap: true,
},
{
entry: ["./src/core.ts"],
platform: "browser",
dts: true,
minify: true,
sourcemap: true,
},
]);Eta has several community-driven integrations for various tools and frameworks:
eta-vscode for template editing.eslint-plugin-eta for linting Eta templates.node-red-contrib-eta for using templates in Node-RED flows.@cedx/koa-eta for rendering templates in the Koa web framework.@rinoshiyo/vite-plugin-eta for using Eta in Vite projects.When working with eta, you can catch specific error classes to distinguish between different failure modes during template processing. All specific errors inherit from EtaError.
EtaError: The base error class for all eta-related issues.EtaParseError: Thrown when there is a syntax error during the parsing phase.EtaRuntimeError: Thrown when an error occurs during template execution (e.g., accessing an undefined variable).EtaFileResolutionError: Thrown when a template file cannot be located.EtaNameResolutionError: Thrown when there is an issue resolving names within the template.Use renderAsync() to render a template asynchronously. This returns a Promise<string>. It behaves similarly to render(), but sets the async option to true internally, which affects how templates are cached and how the template function is executed.
Arguments:
template: A string representing the template name/path or a TemplateFunction.data: An object containing the data to be used in the template.meta: An optional object containing filepath to assist in template resolution.Eta class is the primary entrypoint for the library. It extends the internal core implementation and provides the interface for configuring and executing templates. You can import it directly to manage template compilation and rendering processes.If you have a raw template string that is not stored in a file, use renderString() or renderStringAsync(). These methods compile the string into a function before rendering.
renderString(template, data): Compiles the string and renders it synchronously.renderStringAsync(template, data): Compiles the string and renders it asynchronously (returns a Promise).The compileToString method (available on an Eta instance) converts a template string into a string of executable JavaScript code. This generated string can then be used to create a new function via the new Function() constructor.
This is a low-level method typically used internally by compile(). It respects the current Eta instance configuration and allows for overriding specific options like async for the resulting function.
/**
* Compiles a template string to a function string. Most often users just use `compile()`, which calls `compileToString` and creates a new function using the result
*/
export function compileToString(
this: Eta,
str: string,
options?: Partial<Options>,
): string