@light-stack/templater

Isomorphic document templating over docxtemplater: declare a variable schema, validate human input, then fill a .docx (ArrayBuffer in → ArrayBuffer out). No React, no filesystem, no secrets.

| Concern | docxtemplater | @light-stack/templater | |---------|---------------|--------------------------| | Replace {{full_name}} in a .docx | Yes | Delegates | | Title / description / required for a form | No | Schema | | List missing required fields before convert | No | validate() | | Missing values → empty string | You set nullGetter each time | Fixed policy in convert() |

Install

pnpm add @light-stack/templater

npm install @light-stack/templater

Quick start

import { DocumentTemplater } from '@light-stack/templater';

const templater = new DocumentTemplater({
  variables: [
    {
      placeholder: 'full_name', // appears in the file as {{full_name}}
      title: 'Full name',
      description: 'As in the charter',
      required: true,
    },
    {
      placeholder: 'notes',
      title: 'Notes',
      description: 'Optional remarks',
      required: false,
    },
  ],
  // delimiters: { start: '{{', end: '}}' }, // default
});

const values = { full_name: 'Ada Lovelace', notes: '' };

const result = templater.validate(values);
if (!result.ok) {
  // result.missingRequired — full variable objects (title + description for UI)
  // result.invalidValues — non-string entries
}

const filled = await templater.convert(docxArrayBuffer, values);
// ArrayBuffer — missing/empty/unknown tags → ""

Typical host flow:

1. validate(values)
2. If missingRequired.length, show UI with title + description
3. Cancel → stop. Continue → convert() (blanks in the file)

API

| Export | Description | |--------|-------------| | DocumentTemplater | Constructor + getVariables(), validate(), convert(), inspect() | | TemplaterOptions | { variables, delimiters? } | | Variable | Schema entry (placeholder, title, description, required, optional type: 'string') | | ValidateResult | { ok, missingRequired, unknownKeys, invalidValues } | | Values | Record<string, string> |

Constructor

• variables must be a non-empty unique list; placeholder is the identity (non-empty, no delimiter characters).
• Invalid schema throws TypeError on construct.
• placeholder is without delimiters so PDF/other engines can reuse the same schema later.

validate(values)

• Required is missing if the key is absent, undefined, null, or whitespace-only.
• Non-strings are listed in invalidValues (ok: false).
• Extra keys are allowed and listed in unknownKeys.
• Never reads the document — schema only.

convert(input, values, options?)

• v1 format: docx only (options.format defaults to 'docx').
• Always substitutes; missing values → "". Does not refuse on missing required fields.
• Extra keys in values are passed through to docxtemplater.
• Non-string values throw TypeError.
• Does not mutate input.

inspect(input)

Returns placeholder names found in the file (via docxtemplater’s inspect module) for schema vs file diffs.

Runtime

Isomorphic — works in browser and Node. Pass ArrayBuffer / Uint8Array-backed buffers; no DOM or fs APIs.