Introduction
typed-xlsx is a TypeScript library for Excel reports. You describe the report once as a schema: columns, formulas, styles, summary rows. Then you pass it rows and get an .xlsx file. The same schema works for a 20-row export and for a million rows streamed in batches.
The schema is typed against your row type, so a misspelled field, a formula that points at a missing column, or a selection with an unknown column ID fails in your editor instead of in someone's spreadsheet.
- 01Schema
createExcelSchema<T>()columns, formulas, styles, summaries - 02Table
.table(id, { rows })rows, context, column selection - 03Workbook
createWorkbook()sheets, charts, pivot tables - 04Output
toBuffer() · writeToFile()buffer, file, Node or Web stream
A report in one schema
import { createExcelSchema, createWorkbook } from "typed-xlsx";
type Invoice = {
id: string;
customer: string;
qty: number;
unitPrice: number;
status: "paid" | "pending" | "overdue";
};
const invoices = createExcelSchema<Invoice>()
.column("id", { header: "Invoice #", accessor: "id" })
.column("customer", { header: "Customer", accessor: "customer" })
.column("qty", { header: "Qty", accessor: "qty" })
.column("unitPrice", {
header: "Unit price",
accessor: "unitPrice",
style: { numFmt: "$#,##0.00" },
})
.column("total", {
header: "Total",
formula: ({ refs, fx }) =>
fx.round(refs.column("qty").mul(refs.column("unitPrice")), 2),
style: { numFmt: "$#,##0.00" },
summary: (s) => [s.formula("sum")],
})
.column("status", {
header: "Status",
type: "badge",
accessor: "status",
variants: {
paid: { fill: { color: { rgb: "DCFCE7" } }, font: { color: { rgb: "166534" } } },
pending: {
fill: { color: { rgb: "FEF3C7" } },
font: { color: { rgb: "92400E" } },
},
overdue: {
fill: { color: { rgb: "FEE2E2" } },
font: { color: { rgb: "991B1B" } },
},
},
})
.build();
const workbook = createWorkbook();
workbook.sheet("Invoices", { freezePane: { rows: 1 } }).table("invoices", {
rows: [{ id: "INV-001", customer: "Acme", qty: 10, unitPrice: 299, status: "paid" }],
schema: invoices,
});
await workbook.writeToFile("./invoices.xlsx");
total is written as a real Excel formula, =ROUND((C2*D2),2), so it recalculates when someone edits the sheet. The summary row adds a SUM below the data, and status renders as a colored badge. Leave out one of the three statuses in variants and TypeScript flags it.
The formula is a choice, not a requirement: the same column can be computed in plain TypeScript instead.
Computed in TypeScript or live in Excel
Every computed value, a total, a highlight or a summary, can take one of two paths. Both are fully typed, and you can mix them in the same schema, column by column.
In TypeScript, at export time. Accessor functions, transform, style callbacks and summary reducers receive your typed row and can use anything JavaScript can: dates, lookups, your own helpers, other libraries. The file gets the results as plain values and styles.
import { createExcelSchema } from "typed-xlsx";
type Line = { qty: number; unitPrice: number };
const lines = createExcelSchema<Line>()
.column("qty", { header: "Qty", accessor: "qty" })
.column("unitPrice", { header: "Unit price", accessor: "unitPrice" })
.column("total", {
header: "Total",
accessor: (row) => row.qty * row.unitPrice,
style: ({ row }) => ({ font: { bold: row.qty * row.unitPrice > 5000 } }),
summary: (s) => [
s.cell({
init: () => 0,
step: (sum, row) => sum + row.qty * row.unitPrice,
finalize: (sum) => sum,
}),
],
})
.build();
Live in Excel, with the typed formula DSL. formula, summary.formula() and conditionalStyle write real Excel formulas and conditional formats. When someone edits a quantity, the total, the summary and the highlight update in Excel. TypeScript still checks every reference: refs.column() only accepts columns declared earlier.
import { createExcelSchema } from "typed-xlsx";
type Line = { qty: number; unitPrice: number };
const lines = createExcelSchema<Line>()
.column("qty", { header: "Qty", accessor: "qty" })
.column("unitPrice", { header: "Unit price", accessor: "unitPrice" })
.column("total", {
header: "Total",
formula: ({ refs }) => refs.column("qty").mul(refs.column("unitPrice")),
conditionalStyle: (c) =>
c.when(({ refs }) => refs.column("total").gt(5000), { font: { bold: true } }),
summary: (s) => [s.formula("sum")],
})
.build();
- 1
C2:C3computed while the file is written and stored as a value - 2
D2:D3a formula: Excel recalculates it when Qty or Unit price changes
| In TypeScript | Live in Excel | |
|---|---|---|
| You write | accessor functions, transform, style: ({ row }) =>, summary.cell() | formula, summary.formula(), conditionalStyle, validation rules |
| The file contains | the computed values and styles | formulas and conditional formats |
| When someone edits the file | nothing else changes | totals, formulas and highlights recalculate |
| You can use | anything in JavaScript | what Excel can compute |
| Best for | exports people read, and logic Excel can't express | reports people edit, filter or reuse as a model |
If nobody will edit the numbers, plain TypeScript is the simpler path, and you never need the formula DSL. Reach for it when the workbook has to stay live. See Formula Columns, Dynamic Styles, Conditional Styles and Summary Rows.
What TypeScript checks
- Accessors.
"customer"must be a key ofInvoice, and dot paths like"address.city"are checked all the way down. - Formula references.
refs.column("qty")only accepts columns declared earlier in the chain, so a formula can't point at a column that doesn't exist yet. - Schema context. A schema declared with
createExcelSchema<Row, Context>()requires every table to pass thatcontext. - Selection.
select: { include: [...] }only accepts the schema's column, group and dynamic IDs. - Charts and pivots. Marks and pivot fields only accept columns of the table they read, and only number columns can be plotted or summed.
What you can build with it
| Area | Features |
|---|---|
| Layout | grouped headers, runtime columns, sub-row expansion, several tables per sheet, freeze panes |
| Computed values | in TypeScript: accessor functions, row-based styles, summary reducers; live in Excel: typed formula DSL, summary formulas, native conditional formats |
| Cell types | badges and checkboxes, hyperlinks, sparklines, images, dropdowns and validation |
| Excel | native tables with filters and a totals row, themes, sheet and cell protection |
| Analysis | native charts from your tables, pivot tables and pivot charts Excel keeps in sync |
| Output | buffered or streamed with the same schema, file, buffer, Node and Web streams |
No SheetJS, no ExcelJS: typed-xlsx writes the OOXML parts and the ZIP container itself, with zero runtime dependencies.
Buffered or streamed
createWorkbook() takes all rows at once and is the simplest API. createWorkbookStream() takes rows in batches with table.commit(), for exports that come from a database cursor or are too big to hold in memory. Both accept the same schemas. See Execution Model to choose, and Performance for measured numbers.
When to use something else
typed-xlsx writes reports. It does not read .xlsx files, convert between formats, or edit existing workbooks. For those, use a general spreadsheet library such as SheetJS or ExcelJS. The Comparison page goes through the differences.
Next steps
- Installation
- Quick Start: a complete report, buffered and streamed
- Schema Modes: report layout or native Excel table