typed-xlsx
Getting Started

Introduction

typed-xlsx turns a typed schema into polished XLSX reports, from one row to a million, buffered or streamed, with its own OOXML and ZIP engine.

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.

  1. 01SchemacreateExcelSchema<T>()columns, formulas, styles, summaries
  2. 02Table.table(id, { rows })rows, context, column selection
  3. 03WorkbookcreateWorkbook()sheets, charts, pivot tables
  4. 04OutputtoBuffer() · 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
();
A
B
C
D
1
2
3
Qty
Unit price
Total (TypeScript)
Total (Excel)
10
299
2,990
=(A2*B2)
8
850
6,800
=(A3*B3)
1
2
  1. 1C2:C3computed while the file is written and stored as a value
  2. 2D2:D3a formula: Excel recalculates it when Qty or Unit price changes
In TypeScriptLive in Excel
You writeaccessor functions, transform, style: ({ row }) =>, summary.cell()formula, summary.formula(), conditionalStyle, validation rules
The file containsthe computed values and stylesformulas and conditional formats
When someone edits the filenothing else changestotals, formulas and highlights recalculate
You can useanything in JavaScriptwhat Excel can compute
Best forexports people read, and logic Excel can't expressreports 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 of Invoice, 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 that context.
  • 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

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

Copyright © 2026 Cyprien Thao. Released under the MIT License.