typed-templates

typed-templates

Schema-validated Handlebars template compilation. audit() verifies template slot names match the schema at authoring time. compile(key, data) validates data at runtime then renders.

Choosing the right factory

Scenario	Use
Each template has a different data shape	createHandlebarSchemaMap
Multiple templates share the same data shape	createHandlebarSchemaSingleton

Setup

import * as z from "zod";
import {
  createHandlebarSchemaMap,
  getFileContext,
} from "@stephansama/typed-templates";

const { isLinting, templateDirectory } = getFileContext(import.meta.url);

export const templates = createHandlebarSchemaMap(
  {
    greeting: {
      path: "greeting.hbs",
      schema: z.object({ name: z.string() }),
    },
  },
  { templateDirectory },
);

if (isLinting()) await templates.audit();

getFileContext(import.meta.url) resolves templateDirectory to the directory of the current file — not the working directory. isLinting() returns true only when this file is run directly (e.g. node ./templates.ts), preventing audit() from running on every import.

Core Patterns

Compile a template

const output = await templates.compile("greeting", { name: "Alice" });
// data is validated against the schema before compilation

Singleton: one schema, multiple templates

import * as z from "zod";
import {
  createHandlebarSchemaSingleton,
  getFileContext,
} from "@stephansama/typed-templates";

const { isLinting, templateDirectory } = getFileContext(import.meta.url);

const itemSchema = z.object({
  items: z.array(z.object({ key: z.string(), value: z.string() })),
});

export const itemTemplates = createHandlebarSchemaSingleton(
  ["list.hbs", "table.hbs"],
  itemSchema,
  { templateDirectory },
);

if (isLinting()) await itemTemplates.audit();

const output = await itemTemplates.compile("list.hbs", {
  items: [{ key: "a", value: "1" }],
});