Template rendering

Use template rendering when your workbook is authored in Excel and your application only fills named anchors — cells, ranges, named ranges, tables, and images — rather than constructing worksheet structure from code.

import { renderWorkbookTemplateSafely } from "@ironsheet/node";

const report = await renderWorkbookTemplateSafely("template.xlsx", "report.xlsx", {
  cells: [{ sheetName: "Summary", address: "B2", value: "Q1" }],
  ranges: [{ sheetName: "Summary", startAddress: "A5", values: [["Name", "Amount"]] }],
  names: [{ name: "RevenueRange", values: [["North", 42000]] }],
  tables: [{ tableName: "RevenueTable", rows: [["North", 42000]] }],
  images: [{ imagePartName: "xl/media/image1.png", data: logoPngBytes }]
});

Transactional preflight

Use explicit preflight when you want to validate a user-supplied patch before enabling a workflow or writing a file — for example, to show a user which anchors resolved before they trigger a real render:

const preflight = await workbook.preflightTemplatePatch({
  names: [{ name: "RevenueRange", values: [["North", 42000]] }]
});

console.log(preflight.counts, preflight.targets.names);

The preflight resolves sheets, named ranges, table resize plans, image targets, and image byte signatures without mutating the workbook.

The Node adapter also exposes a standalone preflightWorkbookTemplate(path, patch) helper that opens the file, runs the same preflight, and returns the result — useful when you want to validate a patch against a file path rather than an already-open workbook.

Starter templates

Local demo templates live in templates/manifest.json in the Ironsheet repo and are generated by a TypeScript build script:

npm run templates:build

The generated workbooks are written under templates/generated/ and gitignored. They cover styled reports, macro-enabled models, dashboards with images and charts, pivot-source workbooks, and larger export sheets. Use them for examples, demos, and smoke tests — they are not a substitute for a real Excel-authored compatibility corpus.

Related

• Safe writes — the WorkbookSafeWriteReport shape and how to read it.
• Recipes: render a template — a complete, runnable example.