@eryx/template Module

Jinja-inspired template engine for Luau.

Compiles template source strings into an AST, then evaluates them against a context table to produce rendered output.

Template Syntax

Expressions - {{ expr }}

Outputs the value of an expression, coerced to a string.

{{ name }}              -- variable lookup from context
{{ user.email }}        -- nested/dotted property access
{{ 42 }}               -- numeric literal (integer or decimal)
{{ "hello" }}           -- string literal (supports \n \t \r \\ \")
{{ true }}              -- boolean constant (renders as "true")
{{ false }}             -- boolean constant (renders as "false")
{{ not logged_in }}     -- unary not (negates truthiness)
{{ items[i] }}          -- subscript lookup with a variable key
{{ data["key"] }}       -- subscript lookup with a string key
{{ name | length }}     -- pipe a value through a filter
{{ x | filter1 | f2 }}  -- chain multiple filters left-to-right

Comments - {# ... #}

Ignored by the engine; produces no output.

{# This is a comment #}

Conditionals - {% if … then %}

Conditional blocks. The condition is truthy/falsy (nil and false are falsy; everything else is truthy).

{% if logged_in then %}Welcome!{% end %}

{% if count == 0 then %}
  Empty
{% elseif count < 5 then %}
  A few
{% else %}
  Many
{% end %}

Supported comparison operators: ==, ~=, <, >, <=, >=.

Conditions can be chained with and / or:

{% if role == "admin" and active then %}...{% end %}
{% if x or y then %}...{% end %}

A bare expression (no operator) is treated as a truthiness check:

{% if user then %}...{% end %}
{% if true then %}...{% end %}
{% if not logged_in then %}...{% end %}

Table For-Loop - {% for k, v in tbl do %}

Iterates over key/value pairs of a table expression. Both loop variables are injected into the context and restored after the loop.

{% for i, item in items do %}
  {{ i }}: {{ item.name }}
{% end %}

Numeric For-Loop - {% for i = start, end do %}

Counts from start to end (inclusive). The loop variable is injected into the context and restored after the loop.

{% for i = 1, 5 do %}
  Row {{ i }}
{% end %}

Macros - {% macro name(args) %}

Defines a reusable template block. Arguments become context variables within the macro body.

{% macro greeting(name, title) %}
  Hello, {{ title }} {{ name }}!
{% end %}

Call a macro with {% use %} to provide a body, or {{ }} for a simple inline call:

{% use greeting("Alice", "Dr.") %}
  <p>Extra content here</p>
{% end %}

Inside a macro, {% slot default %} renders the caller's body. Named slots can also be used - see Slots below.

Slots - {% slot name %} / {% fill name %}

Slots define placeholder regions inside a macro body that callers can fill with custom content. Each slot has a default body that is used when the caller does not provide a {% fill %} for it.

{% macro card(title) %}
  <div class="card">
    <h2>{{ title }}</h2>
    {% slot body %}<p>Default body</p>{% end %}
    {% slot footer %}<small>Default footer</small>{% end %}
  </div>
{% end %}

{% use card("My Card") %}
  {% fill body %}<p>Custom body!</p>{% end %}
  {% fill footer %}<small>Custom footer</small>{% end %}
{% end %}

The special slot name "default" is reserved and automatically receives the caller's top-level body content (anything not inside a {% fill %}). You cannot explicitly name a slot "default".

Includes - {% include "path" %}

Inlines another template file at parse time. The path is resolved relative to the directory of the current template file.

{% include "header.html" %}{% end %}
<main>Content</main>
{% include "footer.html" %}{% end %}

Includes accept a body block between {% include %} and {% end %}. The body content is available to the included file as the "default" slot, and named slots can be filled with {% fill %} - just like macro calls.

{% include "layout.html" %}
  {% fill sidebar %}<nav>Custom nav</nav>{% end %}
  {% fill content %}<p>Page body here</p>{% end %}
{% end %}

Inside the included file, use {% slot %} to define the placeholder regions that callers can fill:

{# layout.html #}
<div class="sidebar">{% slot sidebar %}<nav>Default nav</nav>{% end %}</div>
<div class="content">{% slot content %}<p>Default content</p>{% end %}</div>

Literal Text

Anything outside {{ }}, {% %}, and {# #} delimiters is emitted as-is.

Built-in Filters

String Filters

Collection Filters

Numeric Filters

Utility Filters

Error Handling

compile and evaluate are the standard entry points. On failure they call error() with a human-readable string (e.g. "3:7: Unknown filter 'foo'").

If you want the structured TemplateError table instead, call the Raw variants (compileRaw / evaluateRaw), which propagate the table directly so you can inspect .message, .line, .col, and .filepath yourself.

Example

local template = require("@eryx/template")

local tmpl = template.compile("Hello, {{ name | length }}!")
print(template.evaluate(tmpl, { name = "World" })) --> "Hello, 5!"

Summary

Functions

API Reference

Functions

local nodes = template.compile("Hello, {{ name }}!")
print(template.evaluate(nodes, { name = "World" })) --> "Hello, World!"

Types