@office-kit/xlsx

Overview

Office Kit's xlsx library reads, edits, and writes Excel .xlsx workbooks from TypeScript in Node 22+ and modern browsers. It offers typed cell values, styles, formulas, charts, streaming, and byte-for-byte preservation of features it does not model.

Key Features

• Typed reading and writing for .xlsx workbooks from bytes, files, Blob, or fetch responses, with cell values modeled as a discriminated union.
• Write support for styles, number formats, formulas with cached values, Excel tables, data validation, conditional formatting, images, charts, and chartsheets.
• Streaming reader and append-only writer for large sheets, with bounded row buffering and shared-string limits.
• Round-trip preservation of unmodeled parts including pivot tables, VBA projects, threaded comments, external links, and custom XML.
• CI validation of generated OOXML against ECMA-376 schemas plus semantic invariants.
• Subpath imports with tree-shakable ESM exports and no root barrel.

Use Cases

• Programmatically edit existing Excel reports or templates while keeping pivot tables, macros, and other unmodeled parts intact.
• Generate large .xlsx files with streaming writes to keep memory bounded.
• Create typed Excel workbooks with formatting, charts, images, validation, and conditional formatting from TypeScript.
• Read and validate uploaded .xlsx files in Node services or browser applications with typed cell values and error classes.

Getting Started

• Install with pnpm add @office-kit/xlsx or use npm, yarn, or bun.
• Requires Node 22 or later; the package is ESM-only and has no root barrel.
• Load a workbook with loadWorkbook, edit cells with setCell, then save with workbookToBytes or saveWorkbook.
• For large sheets, use createWriteOnlyWorkbook, append rows, then finalize.

Deployment & Requirements

• Node 22 or later is required; Node 18 and 20 EOL are not supported.
• Runs in Node and modern browsers; only the @office-kit/xlsx/node subpath touches fs, while the rest uses Web Streams, Blob, and Uint8Array.
• The package is ESM-only and its shipped types resolve under node16, nodenext, and bundler module resolution.
• The full load and save path must stay under 120 KB minified and brotli-compressed, and the streaming entry under 80 KB.

Before You Adopt

• License: MIT. Review its terms before using, modifying, or distributing the project.
• The project is pre-1.0 alpha, so APIs may shift before 1.0; pin the version for long-running projects.
• Node 22 or later is required; Node 18 and 20 are EOL and not supported.
• Only .xlsx is supported; .xls, .xlsb, .ods, and .csv are out of scope.
• The library has two runtime dependencies: fflate for ZIP and saxes for streaming XML.