template-resolver
Every piece of editable text lives here, in one entity: mail bodies, notification texts, PDF document templates, AI prompts and plain text blocks. What a record is used for is the kind (notification, mail, mail-layout, document-pdf, pdf-layout, ai-prompt, text-block, snippet, image-snapshot).
Reading is one call — ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale }). It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the upsertSystem, upsertTenant, publish and archive write handlers; a SystemAdmin retires or restores a system default with publishSystem and archiveSystem, and a tenant drops its override with resetToSystem. Saving a draft over an active template keeps the active version served and stores the edit beside it (column draft); publish makes it the served version, discardDraft / discardDraftSystem throws it away.
Editing templates is for SystemAdmin only. A TenantAdmin edits only the templates the app unlocks at the mount site, createTemplateResolverFeature({ tenantEditable: [{ kind: "mail", slug: "status-update", access: { roles: ["TenantAdmin"] } }] }), and every write handler enforces that on the server (override, draft, publish, archive, reset, copy-locale, import, resources, set). Each entry carries the access roles allowed to edit it, because a bundled feature cannot know the host’s roles. The same list decides delivery: a tenant override is served (mail, PDF, layouts, text blocks) only while its template is listed in tenantEditable; otherwise the system version is served. A locked override stays stored, a SystemAdmin sees it in the overview marked as not delivered, and listing the template makes it effective again. Tenant rows of a collection mounted with access are always served. A collection mounted without access is SystemAdmin only.
Text an editor should be able to change belongs in a collection, declared at mount: createTemplateResolverFeature({ collections: [{ id, kind, access: { roles }, nav }] }). It appears in the navigation, and access is part of the mount because a bundled feature cannot know the host’s roles. Each collection gets its own <id>-list / <id>-item / <id>-set handlers, so the dispatcher enforces the separation.
How a collection is edited follows from contentFormat: plain gives a text area that stores text, document a WYSIWYG document editor that stores sanitized HTML (bold, italic, headings, lists, links, variable chips). Both offer the collection’s variableSchema as insertable chips and a preview rendered with sample data — an editor sees what {{firstName}} becomes without sending a mail. An app can register its own editor for a format; the last clientFeature that registers a format wins (a conflict logs a warning).
A collection is tenant-wide by default. With ownership: "user" every user keeps their own entries — mail signatures being the obvious case. Those rows live in the separate user-content-entry entity and count as user data, so mounting one registers the user-data hooks for that entity and needs a migration on the app side.
validate dry-runs the write pipeline for a draft (sanitizer, layout rules, placeholders) and reports what the template uses and misses. export-bundle / import-bundle (and import-bundle-system) move one template with all locales and resource files between tenants or environments; copy-locale starts a translation from an existing locale. Layouts are structured: a mail or PDF layout is data-header / data-content / data-signature / data-footer regions, and mjml layout source is system-only.
preview renders a draft (or the stored template) with sample values taken from the example of each declared variable, through the same gates and the same mail renderer as a real send, and returns subject, html, displayHtml (the html with cid images as data URIs for an editor), text, attachments (inline images and files) and checks (images resolved, plain text present, size under 10 MiB, required placeholders used); nothing is saved or sent. send-test mails that rendering to the calling user’s own address only, subject prefixed with [TEST], at most 10 per user and hour; it needs delivery, channel-email and renderer-mail-html to be mounted. send-test-status tells an editor beforehand whether that send can work for the caller (canSend, else reason no_channel or no_address), never returning the address.
Images used by a template (<img data-resource="logo">) are uploaded with resourceUpload, which re-encodes them, stores a file and links it under the key; resourceRemove unlinks it. linkedResources is written only through these two handlers. With purpose: "attachment" and a fileName, resourceUpload stores a PDF, PNG or JPEG as a file attachment of a mail template (original bytes, at most 10) that the mail renderer attaches after the inline images. resourceLinkPdf instead links a document-pdf template under a key: every mail sent from the template then carries that PDF, rendered at send time with the mail’s own variables and locale, under a file name pattern such as invoice-{{number}}.pdf; files and linked PDFs share the limit of 10.
Replaces the former text-content feature; its blocks now live here as kind text-block.
Quick example
Section titled “Quick example”From recipes-legal-pages — the smallest working mount:
// Legal-pages sample//// DACH apps (DE/AT/CH) are required to make an imprint (TMG/DDG §5) and// a privacy policy (GDPR Art. 13) publicly accessible.// That is 1) identical for every app and 2) annoying to build// by hand per app.//// Solution: combine two opt-in bundled features://// - `template-resolver` — the content store (entity `template-resource`,// kind `text-block` with slug+locale+title+content, scoped per tenant).// Also usable for FAQ, About, ToS, marketing snippets — not// legal-specific.//// - `legal-pages` — opt-in wrapper on top of it that registers four fixed public// routes (`/legal/impressum`, `/legal/datenschutz`, `/legal/imprint`,// `/legal/privacy`) and renders Markdown→HTML. Plus a// boot check that fails hard in production when the DE required blocks// are missing.//// Tenant model: 1 app = X tenants = 1 imprint. All subdomains// share the SYSTEM_TENANT_ID version. If you need per-tenant imprints,// you have to put your own routing in front or use the by-slug// query with a tenant-specific tenantId.//// Prerequisites for production:// - `anonymousAccess` must be configured in runProdApp/runDevApp// (defaultTenantId = SYSTEM_TENANT_ID), otherwise the// legal-pages routes answer with 503// - `extraContext.templateResolver = createTemplateResolverApi(db, registry)` must be// wired, otherwise the boot check throws with a wiring hint// - On first boot the TextBlocks must be seeded —// template-resolver/seeding `seedTextBlock` or via API// `template-resolver:write:set` with a TenantAdmin token
import { createLegalPagesFeature, createLegalPagesLayout, LEGAL_REQUIRED_BLOCKS, LEGAL_ROUTES, LEGAL_TERMS_ROUTES,} from "@cosmicdrift/kumiko-bundled-features/legal-pages";import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
// Beide Features aktivieren — template-resolver ist Foundation, legal-pages// requires sie. r.requires({ features: ["template-resolver"] }) greift automatisch im// legal-pages-Feature.export const templateResolverFeature = createTemplateResolverFeature();// `terms: true` adds the opt-in terms routes; the layout puts the app's chrome// around every legal page.export const legalPagesFeature = createLegalPagesFeature({ terms: true, wrapLayout: createLegalPagesLayout({ siteName: "Sample App", footerHtml: (lang) => lang === "de" ? "<footer>Sample App</footer>" : "<footer>Sample App (en)</footer>", }),});
// Re-exports for tests + other demosexport { LEGAL_REQUIRED_BLOCKS, LEGAL_ROUTES, LEGAL_TERMS_ROUTES };📄 On GitHub: samples/recipes/legal-pages/src/feature.ts
Live preview
Section titled “Live preview”
How it fits
Section titled “How it fits”The write commands this feature provides (Provides).
flowchart TB
n_template_resolver["template-resolver"]
subgraph how_provides["Provides"]
n_cmd_template_resolver_write_apply_layout(["apply-layout"])
n_cmd_template_resolver_write_archive(["archive"])
n_cmd_template_resolver_write_archive_system(["archive-system"])
n_cmd_template_resolver_write_copy_locale(["copy-locale"])
n_cmd_template_resolver_write_create_layout(["create-layout"])
n_cmd_template_resolver_write_create_variant(["create-variant"])
n_cmd_more(["+18 more"])
end
n_template_resolver --> n_cmd_template_resolver_write_apply_layout
n_template_resolver --> n_cmd_template_resolver_write_archive
n_template_resolver --> n_cmd_template_resolver_write_archive_system
n_template_resolver --> n_cmd_template_resolver_write_copy_locale
n_template_resolver --> n_cmd_template_resolver_write_create_layout
n_template_resolver --> n_cmd_template_resolver_write_create_variant
n_template_resolver --> n_cmd_more
Provides — write commands this feature registers (dispatch them through the command bus):
template-resolver:write:apply-layouttemplate-resolver:write:archivetemplate-resolver:write:archive-systemtemplate-resolver:write:copy-localetemplate-resolver:write:create-layouttemplate-resolver:write:create-varianttemplate-resolver:write:discard-drafttemplate-resolver:write:discard-draft-systemtemplate-resolver:write:import-bundletemplate-resolver:write:import-bundle-systemtemplate-resolver:write:patch-drafttemplate-resolver:write:publishtemplate-resolver:write:publish-systemtemplate-resolver:write:publish-templatestemplate-resolver:write:reply-snippets-settemplate-resolver:write:reset-to-systemtemplate-resolver:write:resource-link-pdftemplate-resolver:write:resource-removetemplate-resolver:write:resource-uploadtemplate-resolver:write:send-testtemplate-resolver:write:settemplate-resolver:write:signatures-settemplate-resolver:write:upsert-systemtemplate-resolver:write:upsert-tenant
Getting started
Section titled “Getting started”Start with recipes-legal-pages for a step-by-step walkthrough with runnable code and integration tests.
Dependencies
Section titled “Dependencies”- Requires: none
- Activation: always on (not toggleable)
Configuration
Section titled “Configuration”Per-tenant config keys, set via the tenant-admin UI or a seed. 🔒 = encrypted at rest.
| Key | Type | Default | Scope | Who can write | Who can read |
|---|---|---|---|---|---|
default-pdf-layout-slug | text | "" | tenant | TenantAdmin, Admin, SystemAdmin | all |
resource-max-bytes | number (≥ 1) | 2097152 | system | system | TenantAdmin, Admin, SystemAdmin |
Extensions & cross-feature APIs
Section titled “Extensions & cross-feature APIs”- Registers extension:
userData→user-content-entry