Deterministic HTML template renderer. Define a template as an ordered list of
parts plus a compose step; the renderer runs each part, records a trace, and
returns the final HTML.
- Deterministic — same template + props always produce the same HTML.
- Stateless — nothing is remembered between calls.
- Traceable — every part gets a row with
status,chars,ms, and optionalerror. - Two error modes — fail fast (
'throw') or collect-and-continue ('collect'). - String parts only — each part must return a string. Lit
TemplateResults, Promises, or other non-strings are errors. Convert Lit output to a string before it reaches a part.
Working on this repo with an AI agent? Start at AGENTS.md.
Published to GitHub Packages, not npmjs. Point the scope at it first, with a
token that has read:packages:
# .npmrc
@llazyemail:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}npm install @llazyemail/render-template
# or
pnpm add @llazyemail/render-templateimport { renderMany, renderTemplate, type RenderJob, type Template } from '@llazyemail/render-template';
interface Props {
name: string;
}
const welcome: Template<Props> = {
id: 'welcome',
parts: [
{ id: 'greeting', render: (ctx) => `<h1>Hello, ${ctx.props.name}</h1>` },
{ id: 'body', render: () => `<p>Welcome aboard.</p>` },
],
compose: (r) => r.greeting + r.body,
};
const result = renderTemplate(welcome, { name: 'Ada' });
console.log(result.html);
// <h1>Hello, Ada</h1><p>Welcome aboard.</p>
const jobs: RenderJob<Props>[] = [{ template: welcome, props: { name: 'Ada' } }];
const batch = renderMany(jobs, { onError: 'collect' });By default, a broken part throws a RenderError. In CI or batch pipelines,
prefer collect so one bad template doesn't stop the run:
const result = renderTemplate(welcome, { name: 'Ada' }, { onError: 'collect' });
if (!result.ok) {
for (const row of result.parts) {
if (row.status === 'error') console.error(row.id, row.error);
}
}renderMany uses the same RenderOptions.onError. throw skips later jobs.
collect records the failure and continues.
All public types are re-exported from the package root:
Template, TemplatePart, RenderContext, RenderOptions, RenderResult,
PartTrace, PartFailure, SlotValue, RenderJob, ErrorMode, PartStatus.
renderTemplate and renderMany live in src/api.
template-runtime-display— email shell helpers (defineEmailTemplate,renderEmail) on top of this runtime.generate-template— catalog, payload resolution, and disk writes. Consumers should inject their render functions intocreateGeneratorrather than reimplementing generation logic.
defineTemplate validates a template once (non-empty ids, no duplicate part
ids, compose present, compose is a reserved part id), then copies and
freezes it so later edits to your arrays cannot change it.
Slots are caller-supplied fragments. A slot is a string or a function of the
render context. Read them with slot(ctx, id) (missing → '') and
hasSlot(ctx, id) (true even for an empty string):
import { defineTemplate, hasSlot, renderTemplate, slot } from '@llazyemail/render-template';
const card = defineTemplate<{ title: string }>({
id: 'card',
parts: [
{ id: 'title', render: (ctx) => `<h2>${ctx.props.title}</h2>` },
{
id: 'footer',
render: (ctx) => (hasSlot(ctx, 'footer') ? `<footer>${slot(ctx, 'footer')}</footer>` : ''),
},
],
compose: (r) => r.title + r.footer,
});
renderTemplate(card, { title: 'Hi' }, { slots: { footer: (ctx) => `by ${ctx.templateId}` } }).html;
// <h2>Hi</h2><footer>by card</footer>
renderTemplate(card, { title: 'Hi' }).html;
// <h2>Hi</h2> (footer part traced as status "empty")A slot that is not a string or function, or a function slot that returns a
non-string, throws a RenderError.
renderTemplate returns a frozen RenderResult:
| Field | Meaning |
|---|---|
templateId |
The template id |
ok |
false if any part or compose failed |
html |
Output of compose ('' if compose failed in collect mode) |
parts |
One PartTrace per part, in template order |
composeError |
{ name, message } when compose failed in collect mode |
Each PartTrace row is { id, status, html, chars, ms, error? }, where
status is one of:
| Status | When |
|---|---|
ok |
Part returned a non-empty string |
empty |
Part returned '', null or undefined |
error |
Part threw or returned a non-string (error holds { name, message }) |
skipped |
throw mode only: parts after the first failure |
What each mode does with a failing part bad between ok ('A') and later ('C'):
| Mode | Result |
|---|---|
throw (default) |
Throws RenderError with partId: 'bad', message template "b" failed at part "bad": boom, and trace = ok / error / skipped. The original error is cause |
collect |
Returns ok: false, html: 'AC': the failed part contributes '' to compose, and later parts still run |
RenderError also covers invalid templates (partId: 'template') and compose
failures (partId: 'compose').
These are exported for wrappers such as template-runtime-display; most
callers only need renderTemplate, renderMany, defineTemplate, slot
and hasSlot.
| Export | Purpose |
|---|---|
assertTemplate(template) |
The validation defineTemplate runs, without copying |
createContext(templateId, props, slots) |
Build the frozen RenderContext |
normalizeHtml(partId, value) |
null/undefined → '', string → string, anything else → TypeError |
finish(template, ctx, rendered, trace, ok, onError) |
Run compose and build the RenderResult |
okTrace, skippedTrace, describeError, publish |
Build and freeze trace rows |
src/
├── index.ts public surface (re-exports below)
├── types.ts Template, TemplatePart, RenderContext, RenderResult, …
├── errors.ts RenderError
├── api/
│ ├── render.ts renderTemplate, finish
│ └── renderMany.ts renderMany
└── helpers/
├── defineTemplate.ts validate + freeze
├── validation.ts assertTemplate
├── context.ts createContext
├── slot.ts slot, hasSlot
├── html.ts normalizeHtml
└── trace.ts trace rows + publish
test/ Vitest suites (coverage thresholds in vitest.config.ts)
sandbox/example.mjs renders sandbox/generated/*.html for the Sandbox HTML workflow
| Workflow | File | Runs on | What it does |
|---|---|---|---|
| Build | build.yml |
Push and PRs to main |
On Node 22 and 24: npm ci, npm run typecheck, npm run test:coverage (fails under the thresholds in vitest.config.ts: 95% statements/lines/functions, 90% branches), npm run build, then checks every dist/ entry point exists and uploads dist/ as an artifact. |
| Sandbox HTML | sandbox.yml |
PRs, push to main, manual |
Runs npm run sandbox (sandbox/example.mjs) through email-template-workflows and uploads the rendered HTML as the sandbox-html artifact. On PRs it also posts a comment with the file list and sizes, and the run summary shows the same table. |
| Publish to GitHub Packages | publish.yml |
A published GitHub release, or manual | Typecheck, test and build, set the package version from the release tag (v1.2.3 → 1.2.3), then npm publish to GitHub Packages with the built-in GITHUB_TOKEN. A manual run publishes the version already in package.json, or only runs npm publish --dry-run when dry-run is checked. |
There are no scheduled jobs or report issues in this repo.
MIT