Document templates

document-templates separates what a document says from how it looks. The database builds one typed payload per document (the variables), picks the template that fits the legal entity and the buyer's language, and returns both. You render the result to HTML, then to PDF with whatever tool you use. An issued invoice keeps the template and texts it had when it was issued, so editing a template never changes a document that already went out.

better-supabase add document-templates

import { createDocumentTemplates } from "better-supabase/blocks/document-templates";

The module requires tenant, permissions and legal entities. It reads the tables of invoices, quotes, orders, shipments and contacts when they are installed, and a document type whose block is missing fails with the hint DOCUMENT_TYPE_UNAVAILABLE. With outbox it records the events, and with audit every change is audited.

TablesCopy Anchor Link

A frozen render shows to someone who can read the source document. A statement has no row of its own, so its render shows to template managers.

Saving templatesCopy Anchor Link

A template body is HTML you write with placeholders. The slot is the document type, the name (default default), the legal entity (null for the organization) and the language (null for any language). Saving a changed body raises the version by one.

const db = betterSupabase.server(...).forContext(ctx);

await db.documentTemplates
  .saveTemplate({
    documentType: "invoice",
    legalEntityId: bv.id,
    language: "nl",
    body: `
      <h1>Factuur {{document.number}}</h1>
      <p>{{buyer.name}}</p>
      <table>
        {{#each lines as line}}
        <tr><td>{{line.description}}</td><td>{{line.amount | money}}</td></tr>
        {{/each}}
      </table>
      <p>Totaal {{totals.total | money}}, te betalen voor {{document.dueOn | date}}</p>
      {{texts.footer}}
    `,
  })
  .orThrow();

A template that names an unknown variable, filter or block fails with a hint code and is not saved:

validate runs the same check in the database and returns the issues without saving, for an editor.

Text blocksCopy Anchor Link

A text block is a reusable text. It follows the same lookup as a template and can read the variables of any document type, so one footer works on invoices and quotes.

await db.documentTemplates
  .saveTextBlock({
    key: "footer",
    language: "nl",
    body: "Betaling binnen 30 dagen.",
  })
  .orThrow();

Which template a document getsCopy Anchor Link

resolveTemplate and render pick the first template that exists, in this order:

1. The legal entity, in the language.
2. The legal entity, for any language.
3. The organization, in the language.
4. The organization, for any language.

A regional language such as nl-NL matches nl. A null legal entity means the default entity. Text blocks use the same order for each key. When nothing matches in the requested language, a template in another language still beats no template, and source says so (entity_other_language, organization_other_language). An inactive template leaves the chain.

RenderingCopy Anchor Link

render returns the variables of a document with the template and text blocks chosen for it. The language is the one you pass, else the buyer's language.

const rendered = await db.documentTemplates
  .render({ documentType: "invoice", documentId: invoice.id })
  .orThrow();

rendered.template?.source; // "entity_language"
rendered.variables.totals.total; // "121000", minor units as text
rendered.blocks.footer; // the text block the template reads

renderHtml renders the chosen template to HTML. Every value is escaped, so a buyer called <script> prints as text, and only the markup in your template is HTML. A template the database accepted always renders. It runs in pure TypeScript on every runtime and adds no dependency.

const html = await db.documentTemplates
  .renderHtml({ documentType: "invoice", documentId: invoice.id })
  .orThrow();

renderDocumentHtml is the same renderer without the database, for a document you already hold. Amounts are formatted with Intl from digits, so no amount passes through a float.

Frozen documentsCopy Anchor Link

Issuing an invoice or credit note freezes its render when the transaction commits: the variables, the template body and version, and the text blocks are copied into rendered_documents. From then on render returns that copy, so editing a template, a text block or the party's address does not change the document. Pass fresh: true to render with today's templates, for a preview.

Quotes, orders, delivery notes, dunning letters and statements are not frozen automatically. Call freeze when you send one:

await db.documentTemplates
  .freeze({ documentType: "quote", documentId: quote.id })
  .orThrow();

A frozen render cannot be updated or deleted (DOCUMENT_SNAPSHOT_IMMUTABLE), and freezing twice returns the first copy. A bulk import does not freeze.

The variable contractCopy Anchor Link

The contract is versioned (DOCUMENT_CONTRACT_VERSION, now 1). Every document type has these keys, and most add more:

Dunning letters add document.level and document.textKey, and statements add the open invoices as lines. A key the source does not have is null. Amounts are minor units as text, so a bigint never loses precision.

contract(type) reads the variable paths and types from the database, and documentContract(type) and DOCUMENT_VARIABLES give the same list in TypeScript, with a description of each variable. New variables arrive as new optional keys. Removing or retyping one needs a new contract version.

Importing templatesCopy Anchor Link

The block registers two import targets, document_template and document_text_block. An item names the legal entity by its code or id:

{ documentType: "invoice", language: "nl", legalEntity: "NL01", body: "<h1>...</h1>" }
{ key: "footer", language: "nl", body: "Betaling binnen 30 dagen." }

Importing a slot again changes its body and raises the version, so the import is safe to repeat.

EventsCopy Anchor Link

The hooks before_document_template_save, after_document_template_save, before_document_text_block_save and after_document_text_block_save run around the saves.

FunctionsCopy Anchor Link

The client calls these better_supabase functions: save_document_template, set_document_template_active, get_document_template, list_document_templates, save_document_text_block, list_document_text_blocks, resolve_document_template, render_document, freeze_document, document_template_contract and validate_document_template.