Getting started
Install an Ironsheet adapter and make your first validation-gated edit.
Ironsheet 0.1 is an active MVP. For Node.js applications, install the safe-write adapter and start from an existing Excel-authored workbook — Ironsheet edits the file you already have rather than generating a new one from scratch.
Install the Node adapter
npm install @ironsheet/node@ironsheet/node bundles the runtime-neutral @ironsheet/core engine with
filesystem IO, zlib compression, safe writes, and template render helpers.
It is the package most Node applications want.
Render a template safely
renderWorkbookTemplateSafely fills named anchors — cells, ranges, named
ranges, tables, and images — in an Excel-authored template in one
transactional patch:
import { renderWorkbookTemplateSafely } from "@ironsheet/node";
const report = await renderWorkbookTemplateSafely("template.xlsm", "output.xlsm", {
names: [
{
name: "RevenueRange",
values: [
["Region", "Amount"],
["North", 42000]
]
}
],
tables: [
{
tableName: "RevenueTable",
rows: [
["North", 42000],
["South", 31500]
]
}
],
images: [
{
imagePartName: "xl/media/image1.png",
data: await fetchLogoBytes()
}
]
});
if (!report.wrote) {
throw new Error(`Workbook failed validation: ${report.validation.summary.errors} error(s)`);
}
console.log(report.diff.summary);Safe renders preflight every target before applying changes. If a named range, table, cell, range, or image is missing, Ironsheet fails before touching the workbook — no partial writes.
Read the safe-write report
Every safe write returns a WorkbookSafeWriteReport — treat it as a write
receipt rather than a side effect you can ignore:
type WorkbookSafeWriteReport = {
diagnostics: Diagnostic[];
diff: PackageDiff;
validation: ValidationReport;
wrote: boolean;
};if (report.wrote) {
console.log("validated output written", report.diff.summary);
} else {
console.error("output suppressed", report.validation.summary);
}Validation-gated writes
Safe writes suppress output when validation errors are present. Ironsheet
will not produce a corrupt file — report.wrote is false and no output
bytes are written unless you explicitly opt in with allowValidationErrors,
which is intended for debugging or fixture capture only.
report.diff.summary distinguishes a real content edit (changed) from pure
compression noise (repacked) — see Safe writes
for the full breakdown.
Custom edits and other runtimes
For a custom edit instead of a template fill, use mutateWorkbookFile — the
same validation-gated flow, but with direct access to the workbook's mutation
methods:
import { mutateWorkbookFile } from "@ironsheet/node";
const report = await mutateWorkbookFile("template.xlsx", "report.xlsx", async (workbook) => {
await workbook.patchCell("Summary", "B2", "Q1");
await workbook.patchNamedRange("RevenueRange", [["North", 42000]]);
await workbook.replaceTableRows("RevenueTable", [["North", 42000]]);
});
if (!report.wrote) {
throw new Error("Ironsheet refused to write an invalid workbook");
}Working in a browser instead of Node? See the Browser guide
for @ironsheet/browser, which adapts the same workbook engine to Blob,
File, and ArrayBuffer.