trellis (core engine)
trellis is the template engine at the heart of the SDK: a natural HTML
template engine for Dart. Templates are valid HTML that browsers render as
prototypes without a server, with a fragment-first design built for
hypermedia-driven frameworks like HTMX.
This guide covers the engine's runtime API – how you construct and configure the engine, load templates, render fragments, validate, and extend it. It assumes you already know the template language:
- New to Trellis? Start with Getting Started.
- Looking up an attribute or expression? See the
Syntax Reference – every
tl:*attribute, the<tl:block>element, and every expression form, each with a worked example.
Requirements and installation
- Dart SDK
^3.10.0
dart pub add trellis
The only runtime dependency is package:html, the Dart team's HTML5 parser.
Rendering
import 'package:trellis/trellis.dart';
final engine = Trellis();
final html = engine.render(
'<h1 tl:text="${title}">Default Title</h1>',
{'title': 'Hello, Trellis!'},
);
// <h1>Hello, Trellis!</h1>
render() is synchronous. renderFile() is asynchronous only because it reads
from disk. For the full template language – text, conditionals, iteration,
fragments, attributes, expressions – see the
Syntax Reference.
Configuration
The Trellis constructor takes named options:
Trellis(
loader: FileSystemLoader('templates/'), // template source
cache: true, // DOM caching with deep-clone (default: true)
devMode: false, // file watching for dev (default: false)
maxCacheSize: 100, // LRU eviction threshold (default: 256)
prefix: 'tl', // attribute prefix (default: 'tl')
strict: false, // throw on undefined variables/members (default: false)
messageSource: ..., // i18n MessageSource implementation
locale: 'en', // default locale for message lookup
processors: [...], // additional custom Processor instances
dialects: [...], // Dialect instances contributing processors + filters
includeStandard: true, // include the built-in StandardDialect (default: true)
)
TrellisContext is a fluent builder for constructing rendering-context maps:
final context = TrellisContext()
.set('title', 'Hello')
.set('user', {'name': 'Alice'})
.setAll({'items': ['a', 'b', 'c']})
.build();
final html = engine.render(template, context);
Strict mode
With strict: true, undefined variables and members throw ExpressionException
instead of rendering empty. Use it to catch template typos early.
Template loaders
A loader tells the engine where to find named templates for renderFile() and
cross-file fragment includes (~{file :: fragment}):
FileSystemLoader(basePath)– loads from the filesystem, enforcing path-traversal and symlink-escape protection.AssetLoader(packageUri)– loads from Dart package assets (JIT only; not AOT-compatible).CompositeLoader(delegates)– tries multiple loaders in order with fallback.MapLoader(templates)– in-memory templates, useful for testing.
FileSystemLoader rejects absolute paths, .. traversal, and symlink escapes
outside the base directory, throwing TemplateSecurityException.
Fragments and HTMX
Fragments are the bridge to HTMX partial responses: define a piece with
tl:fragment, then render just that piece. See the
Fragments reference for the template-side syntax; the
engine side is the render API:
final engine = Trellis(loader: FileSystemLoader('templates/'));
// Full page render
final page = engine.render(pageTemplate, {'items': items});
// HTMX partial — render only the named fragment
final fragment = engine.renderFragment(
pageTemplate,
fragment: 'itemList',
context: {'items': items},
);
// Render multiple fragments in one call (e.g. HTMX out-of-band swaps)
final fragments = engine.renderFragments(
pageTemplate,
fragments: ['header', 'itemList'],
context: {'items': items},
);
For a framework-specific request/response layer – middleware, response helpers, and HTMX detection – use the integration package for your server: trellis_shelf, trellis_dart_frog, or trellis_relic.
Dev mode (file watching)
Enable devMode to reload templates automatically when files change on disk:
final engine = Trellis(
loader: FileSystemLoader('templates/', devMode: true),
devMode: true,
);
// Templates are re-read automatically when modified.
// Call close() when shutting down to release the file watcher:
await engine.close();
When devMode is false (the default), no file watcher is created and there is
zero runtime overhead. Trellis.close() also closes the associated
FileSystemLoader; if you share a loader across engines, manage its lifecycle
separately.
For live browser refresh on template changes, pair this with trellis_dev.
Template validation
Validate templates in unit tests with the matcher from
package:trellis/testing.dart:
import 'package:test/test.dart';
import 'package:trellis/testing.dart';
void main() {
test('template is valid', () {
expect('<p tl:text="${name}">x</p>', isValidTemplate());
});
}
For direct validation, use TemplateValidator:
final validator = TemplateValidator();
final issues = validator.validate('<p tl:text=""></p>');
For CI or local checks, validate a directory recursively:
dart run trellis:validate # scans ./templates
dart run trellis:validate templates # or pass the directory positionally
dart run trellis:validate --dir templates --prefix tl
dart run trellis:validate --strict # CI gate: warnings also fail the build
CLI behavior:
- Success prints nothing and exits
0. - Validation issues are printed to
stderraspath:line: severity: message (attribute). - Validation errors exit
1. - Warnings – including the silent HTML5-parser mutations that strip
tl:*directives (duplicatetl:attr, table/select foster-parenting) – are printed but exit0by default. Pass--strict(alias--fatal-warnings) to make them exit1too.
For CI, run with --strict so those silent-mutation warnings become a real
gate. Equivalently, assert zero issues inside dart test with
isValidTemplate() over your shipping templates.
Template testing
Testing utilities are built into the core package via testing.dart – no extra
dependency needed:
import 'package:trellis/testing.dart';
import 'package:test/test.dart';
void main() {
final engine = testEngine(templates: {
'card': '<div tl:fragment="card"><h2 tl:text="${title}">Title</h2></div>',
});
test('card fragment renders title', () {
final html = testFragment(engine, 'card', 'card', {'title': 'Hello'});
expect(html, hasElement('h2', withText: 'Hello'));
expect(html, hasNoElement('.missing'));
});
test('snapshot', () async {
await expectSnapshotFromSource(engine, '<p tl:text="${msg}">x</p>', {'msg': 'hi'});
});
}
Extending the engine
Custom processors
Implement the Processor interface to add a new tl:* attribute. A processor
declares its attribute name, priority, and whether to recurse into children:
class HighlightProcessor implements Processor {
@override
String get attribute => 'highlight';
@override
ProcessorPriority get priority => ProcessorPriority.afterContent;
@override
bool get autoProcessChildren => true;
@override
bool process(Element element, String value, ProcessorContext context) {
element.attributes['style'] =
'${element.attributes['style'] ?? ''}background:yellow';
element.attributes.remove('tl:highlight');
return true;
}
}
final engine = Trellis(processors: [HighlightProcessor()]);
Dialects
A Dialect groups processors and filters into a reusable feature set:
class MyDialect implements Dialect {
@override
String get name => 'MyDialect';
@override
List<Processor> get processors => [HighlightProcessor()];
@override
Map<String, Function> get filters => {
'shout': (v) => v.toString().toUpperCase() + '!!!',
};
}
final engine = Trellis(dialects: [MyDialect()]);
// Use only custom dialects, omitting the built-in StandardDialect:
final minimal = Trellis(dialects: [MyDialect()], includeStandard: false);
The built-in CssDialect from trellis_css is an
example of a dialect you can register to add the tl:scope processor.
Public API
| Method / Property | Returns | Description |
|---|---|---|
render(source, context) |
String |
Render template string |
renderFile(name, context) |
Future<String> |
Load and render template file |
warmUp(names) |
Future<WarmUpResult> |
Pre-load named templates into the DOM cache |
warmUpAll() |
Future<WarmUpResult> |
Discover and pre-load templates from FileSystemLoader/MapLoader |
renderFragment(source, fragment:, context:) |
String |
Render named fragment from string; a parameterised fragment is addressed by bare name (details) |
renderFileFragment(name, fragment:, context:) |
Future<String> |
Load file and render named fragment |
renderFragments(source, fragments:, context:) |
String |
Render multiple fragments concatenated, against one shared context (details) |
renderFileFragments(name, fragments:, context:) |
Future<String> |
Load file and render multiple fragments |
clearCache() |
void |
Clear DOM cache and reset statistics |
cacheStats |
CacheStats |
Hit/miss/size metrics for the DOM cache plus expressionCacheSize |
close() |
Future<void> |
Release file-watch resources; also closes the loader (no-op when devMode is false) |
ExpressionEvaluator can be used standalone for expression evaluation without
templates:
final evaluator = ExpressionEvaluator(strict: true);
final result = evaluator.evaluate(r'${a} + ${b}', {'a': 1, 'b': 2}); // 3
Error handling
| Exception | When |
|---|---|
TemplateException |
Base class for all template errors |
ExpressionException |
Malformed or unevaluable expression (also thrown in strict mode for undefined variables) |
FragmentNotFoundException |
Named fragment not found in template |
TemplateNotFoundException |
Template file not found by loader |
TemplateSecurityException |
Path-traversal or symlink-escape attempt |
Security
tl:textalways HTML-escapes output – safe for user-supplied data.tl:utextrenders unescaped HTML – only use it with trusted content to avoid XSS.tl:inlineinjavascript/cssmode escapes output, including</script>and</style>closing tags.FileSystemLoaderrejects absolute paths,..traversal, and symlink escapes outside the base directory.
See Text and Attributes for the escaping rules that bear on template syntax.