@singleton-sd/post-kit-compiler

Template compiler for PostKit. Reads Git-backed email template source files (template.json, metadata.json, preview.json), validates them, and produces a compiled CompiledTemplate artifact for use by post-kit-publisher and apps/api.

HTML renderer and variable engine

HTML is produced by @usewaypoint/email-builder renderToStaticMarkup (EmailBuilder.js JSON → email HTML).

Subject lines and {{variable}} substitution in that HTML use Handlebars ^4.7.8 (the version declared in this package). Handlebars is not the HTML renderer.

Until send-time substitution, compiled templateHtml keeps Handlebars placeholders. compile() still renders preview.json through Handlebars to fail fast on invalid templates.

Installation

pnpm add @singleton-sd/post-kit-compiler

API

import { compile, compileFromDirectory, renderPreview, validateSource, CompilerError } from '@singleton-sd/post-kit-compiler';

compile(source, options?)

Validates and compiles a TemplateSource object into a CompiledTemplate.

const result = await compile({
  templateJson: { document: { type: 'EmailLayout', data: {} } },
  metadata: {
    key: 'marketing.contact-us',
    name: 'Contact Us',
    subject: 'New message from {{name}}',
    variables: ['name', 'email', 'message'],
    schemaVersion: '1',
  },
  previewData: { name: 'Jane Doe', email: '[email protected]', message: 'Hello!' },
});

console.log(result.manifest.contentHash); // SHA-256 hex

compileFromDirectory(dir, options?)

Reads template.json, metadata.json, and preview.json from dir and delegates to compile().

const result = await compileFromDirectory('./content/email-templates/marketing.contact-us');

renderPreview(source)

Same validation and EmailBuilder render path as compile(), but returns the Handlebars-substituted HTML string (preview values applied). Intended for the admin editor preview pane. Does not hash content and does not use node:crypto or the filesystem.

Browser bundles must import from @singleton-sd/post-kit-compiler/preview (not the package root). The root entry still re-exports renderPreview for Node tooling, but also pulls in compile / filesystem helpers.

import { renderPreview } from '@singleton-sd/post-kit-compiler/preview';

const html = await renderPreview(source);

validateSource(source)

Dry-run validation — returns { ok: true } or { ok: false; errors: string[] }. Does not throw.

const validation = validateSource(source);
if (!validation.ok) {
  console.error(validation.errors);
}

CompilerError

Thrown by compile() and compileFromDirectory() on validation or render failures. Has a code property:

| Code | Meaning | |---|---| | INVALID_TEMPLATE_JSON | template.json is missing or not valid JSON | | INVALID_METADATA | metadata.json or preview.json is missing, not valid JSON, or fails schema validation | | MISSING_PREVIEW_VARIABLE | A variable declared in metadata.variables is absent from previewData | | RENDER_FAILURE | HTML or subject template rendering failed |

Development

pnpm test   # type-check + run tests
pnpm build  # emit CommonJS to dist/
pnpm lint   # covered by root eslint