@molecule/api-templating

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Provider-agnostic template rendering interface for molecule.dev.

Defines the TemplateProvider interface for rendering templates, compiling templates for reuse, and registering helpers and partials. Bond packages (Handlebars, MJML, Liquid, etc.) implement this interface. Application code uses the convenience functions (render, compile, renderCompiled, registerHelper, registerPartial) which delegate to the bonded provider.

Quick Start

import { setProvider, render, compile, renderCompiled } from '@molecule/api-templating'
import { provider as handlebars } from '@molecule/api-templating-handlebars'

setProvider(handlebars)

const html = await render('Hello {{name}}!', { name: 'World' })

const compiled = await compile('Hello {{name}}!')
const fast = await renderCompiled(compiled, { name: 'Fast' })

Type

core

Installation

npm install @molecule/api-templating @molecule/api-bond @molecule/api-i18n

API

Interfaces

CompiledTemplate

A compiled template that can be rendered multiple times with different data without re-parsing.

interface CompiledTemplate {
  /** An opaque identifier for the compiled template. */
  id: string

  /** The original template source string. */
  source: string

  /**
   * Provider-specific compiled representation.
   * This is intentionally opaque — callers use `renderCompiled()` to render.
   */
  compiled: unknown
}

RenderOptions

Configuration options for template rendering.

interface RenderOptions {
  /** Whether to HTML-escape output by default. Defaults to `true`. */
  escape?: boolean

  /** Additional helpers available during rendering. */
  helpers?: Record<string, TemplateHelper>

  /** Additional partials available during rendering. */
  partials?: Record<string, string>
}

TemplateConfig

Configuration options for template providers.

interface TemplateConfig {
  /** Whether to HTML-escape output by default. Defaults to `true`. */
  escape?: boolean

  /** Directory path to load template files from. */
  templateDir?: string

  /** File extension for template files (e.g., `'.hbs'`, `'.mjml'`). */
  fileExtension?: string
}

TemplateProvider

Template provider interface.

All template providers must implement this interface. Bond packages (Handlebars, MJML, Liquid, etc.) provide concrete implementations.

interface TemplateProvider {
  /**
   * Renders a template string with the provided data.
   *
   * @param template - The template source string.
   * @param data - Key-value pairs to inject into the template.
   * @param options - Optional rendering configuration.
   * @returns The rendered output string.
   */
  render(template: string, data: Record<string, unknown>, options?: RenderOptions): Promise<string>

  /**
   * Pre-compiles a template for repeated rendering. Use this when the same
   * template will be rendered multiple times with different data.
   *
   * @param template - The template source string.
   * @returns A compiled template object.
   */
  compile(template: string): Promise<CompiledTemplate>

  /**
   * Renders a previously compiled template with the provided data.
   * This is faster than `render()` for templates used multiple times.
   *
   * @param compiled - A compiled template from `compile()`.
   * @param data - Key-value pairs to inject into the template.
   * @returns The rendered output string.
   */
  renderCompiled(compiled: CompiledTemplate, data: Record<string, unknown>): Promise<string>

  /**
   * Registers a named helper function available in all templates.
   *
   * @param name - The helper name used in templates (e.g., `{{uppercase name}}`).
   * @param fn - The helper implementation.
   */
  registerHelper(name: string, fn: TemplateHelper): void

  /**
   * Registers a named partial template that can be included in other templates.
   *
   * @param name - The partial name used in templates (e.g., `{{> header}}`).
   * @param template - The partial template source string.
   */
  registerPartial(name: string, template: string): void
}

Types

TemplateHelper

A template helper function registered with the template engine. Receives arguments from the template and returns a string.

type TemplateHelper = (...args: unknown[]) => string

Functions

compile(template)

Pre-compiles a template for repeated rendering.

function compile(template: string): Promise<CompiledTemplate>

• template — The template source string.

Returns: A compiled template object.

getProvider()

Retrieves the bonded template provider, throwing if none is configured.

function getProvider(): TemplateProvider

Returns: The bonded template provider.

hasProvider()

Checks whether a template provider is currently bonded.

function hasProvider(): boolean

Returns: true if a template provider is bonded.

registerHelper(name, fn)

Registers a named helper function available in all templates.

function registerHelper(name: string, fn: TemplateHelper): void

• name — The helper name used in templates.
• fn — The helper implementation.

registerPartial(name, template)

Registers a named partial template that can be included in other templates.

function registerPartial(name: string, template: string): void

• name — The partial name used in templates.
• template — The partial template source string.

render(template, data, options)

Renders a template string with the provided data.

function render(
  template: string,
  data: Record<string, unknown>,
  options?: RenderOptions,
): Promise<string>

• template — The template source string.
• data — Key-value pairs to inject into the template.
• options — Optional rendering configuration.

Returns: The rendered output string.

renderCompiled(compiled, data)

Renders a previously compiled template with the provided data.

function renderCompiled(compiled: CompiledTemplate, data: Record<string, unknown>): Promise<string>

• compiled — A compiled template from compile().
• data — Key-value pairs to inject into the template.

Returns: The rendered output string.

setProvider(provider)

Registers a template provider as the active singleton. Called by bond packages during application startup.

function setProvider(provider: TemplateProvider): void

• provider — The template provider implementation to bond.

Available Providers

| Provider | Package | | ---------- | ------------------------------------- | | Templating | @molecule/api-templating-handlebars | | Templating | @molecule/api-templating-mjml |

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-bond ^1.0.1
• @molecule/api-i18n ^1.0.1

Runtime Dependencies

• @molecule/api-bond

• @molecule/api-i18n

• User input goes in the DATA argument, never into the template string. A template is CODE to the engine (expressions, helpers, partials) — concatenating user text into it is template injection. render(trustedTemplate, userData) is the safe shape.

• Interpolated values are HTML-escaped by default in the HTML bonds; raw interpolation (e.g. Handlebars triple-stash, or a bond's escape: false config) re-opens XSS — reserve it for markup you generated server-side.

• Register helpers/partials BEFORE rendering templates that use them — do registerHelper/registerPartial at startup alongside setProvider, not lazily in handlers.

• compile() returns an opaque {@link CompiledTemplate} — reuse it for hot paths (e.g. an email loop) instead of re-parsing the same template per render.

• This package renders STRINGS; pair it with the emails/pdf packages for delivery (e.g. the MJML bond turns email markup into inline-styled HTML for sendMail).