API overview

The full TypeScript API is bundled with the npm package — your editor will autocomplete every export. This page is the map: where to look for each kind of thing.

The full, section-organized reference lives at /api — every export rendered with its signature, parameters, and source link. This page is the conceptual map you reach for first.

Subpath entries

The package has no root barrel — every export lives behind a section subpath, so your editor’s autocomplete only surfaces what’s relevant to the area you’re working in. Each export has exactly one home (no convenience re-exports).

// Load and save xlsx — loadWorkbook / saveWorkbook / workbookToBytes,
// plus byte-level Source/Sink types and browser helpers (Blob/Response/Stream).
import { loadWorkbook, saveWorkbook, fromResponse } from '@office-kit/xlsx/io';

// Node fs glue (filesystem / Readable / Writable bridges + Buffer source/sink).
import { fromFile, toFile, fromBuffer, fromReadable } from '@office-kit/xlsx/node';

// Streaming — read iter, write-only append.
import { loadWorkbookStream, createWriteOnlyWorkbook } from '@office-kit/xlsx/streaming';

// Workbook root model — createWorkbook, addWorksheet, defined names, etc.
import { createWorkbook, addWorksheet } from '@office-kit/xlsx/workbook';

// Worksheet — setCell, getCell, mergeCells, freeze panes, tables, hyperlinks…
import { setCell, mergeCells } from '@office-kit/xlsx/worksheet';

// Cell value-model + inline rich text.
import { makeCell, makeRichText } from '@office-kit/xlsx/cell';

// Styles — fonts, fills, borders, alignment, number formats, named styles.
import { makeFont, setBold } from '@office-kit/xlsx/styles';

// Charts (legacy `c:` + chartex `cx:`).
import { makeBarChart, makeChartSpace } from '@office-kit/xlsx/chart';

// Drawings — anchors, images, chart placement.
import { addImageAt, loadImage } from '@office-kit/xlsx/drawing';

Other available subpaths: @office-kit/xlsx/chartsheet, @office-kit/xlsx/packaging, @office-kit/xlsx/utils, @office-kit/xlsx/xml, @office-kit/xlsx/zip, @office-kit/xlsx/schema.

Each entry has the bundle budgets enforced by pnpm size in CI. All exports are tree-shakable — "sideEffects": false is set in package.json.

Workbook model

The library exposes a layered model split across subpaths:

• I/O (@office-kit/xlsx/io) — loadWorkbook, saveWorkbook, workbookToBytes plus byte-level XlsxSource / XlsxSink types and browser-safe helpers (fromBlob, fromResponse, fromStream, fromArrayBuffer, toBlob, toArrayBuffer).
• Node fs glue (@office-kit/xlsx/node) — fromFile, toFile, fromBuffer, toBuffer, fromReadable, toWritable.
• Streaming (@office-kit/xlsx/streaming) — loadWorkbookStream, createWriteOnlyWorkbook.
• Workbook (@office-kit/xlsx/workbook) — createWorkbook, addWorksheet, Workbook shape, defined names, calc properties, file metadata.
• Worksheet (@office-kit/xlsx/worksheet) — cells, rows, columns, merged cells, freeze panes, autoFilter, Tables, hyperlinks, data validations, conditional formatting, legacy comments.
• Cell (@office-kit/xlsx/cell) — Cell shape, formula helpers, inline rich-text composition.
• Styles (@office-kit/xlsx/styles) — Font, Fill, Border, Alignment, Protection, NumberFormat, full stylesheet pool with dedup, named styles + DXF.
• Drawings (@office-kit/xlsx/drawing) — anchors, images (PNG/JPEG/GIF/BMP/WebP/TIFF/SVG/EMF/WMF) with auto-detected format + dimensions.
• Charts (@office-kit/xlsx/chart) — 16 legacy c: chart kinds + 8 cx: chartex kinds (Sunburst, Treemap, Waterfall, Histogram, Pareto, Funnel, BoxWhisker, RegionMap).
• Packaging / XML / ZIP / schema (@office-kit/xlsx/packaging, @office-kit/xlsx/xml, @office-kit/xlsx/zip, @office-kit/xlsx/schema) — the OPC layer below the workbook plus low-level XML reader / writer + Excel namespace constants. You won’t touch these directly unless you’re extending the library.

Cell helpers

Coordinates are 1-indexed (row=1, col=1 is A1). For A1 ↔ row/col conversion, reach for @office-kit/xlsx/utils.

Loading and saving

// Source-side
loadWorkbook(source: XlsxSource): Promise<Workbook>
loadWorkbookStream(source: XlsxSource): Promise<StreamingWorkbook>

// Sink-side
workbookToBytes(wb: Workbook): Promise<Uint8Array>
saveWorkbook(wb: Workbook, sink: XlsxSink): Promise<void>
createWriteOnlyWorkbook(sink: XlsxSink): Promise<WriteOnlyWorkbook>

loadWorkbook / saveWorkbook / workbookToBytes come from @office-kit/xlsx/io; loadWorkbookStream / createWriteOnlyWorkbook from @office-kit/xlsx/streaming.

XlsxSource accepts anything from a Uint8Array to a ReadableStream<Uint8Array> to a Blob to a Node Readable. The matching from* helpers are split between @office-kit/xlsx/node (fs / buffer / readable) and @office-kit/xlsx/io (blob / response / web stream / array buffer).

Errors

• Encrypted workbook — we detect the CFB Compound Document magic and throw EncryptedWorkbookError. Decrypt with msoffcrypto-tool first.
• ZIP64 write — workbooks with > 65 535 entries get a ZIP64 EOCD record + locator. Read works too.
• Malformed XML — every XML parse path runs through a single hardened SAX layer. Errors include the file part path so you know which xl/... part triggered it.

Migration

If you’re coming from openpyxl: see docs/migrate-from-openpyxl.md in the repo for the function-by-function map.