node-xlsx

node-xlsx is a lightweight Node.js library for parsing and building Excel (.xlsx) files, wrapping the battle-tested SheetJS xlsx engine behind a simpler, TypeScript-friendly API. It converts spreadsheets to and from plain JavaScript arrays, so reading a workbook’s contents or generating a new one takes only a few lines of code instead of learning SheetJS’s full surface area.

Common use cases include exporting report data to Excel from a web backend, generating downloadable spreadsheets on demand, and ingesting user-uploaded Excel data into structured records. The library also ships a small CLI that builds an .xlsx file from a JSON payload piped over stdin, useful for quick scripting or shell-based automation without writing any Node.js code.

What You Get

• Buffer or file-path input for parsing — pass a Buffer, a Uint8Array, or a path string directly to parse()
• Multi-sheet workbook building via build(), each sheet given a name and a 2D array of row data
• Column width, merged-cell-range, and worksheet-protection options through sheetOptions
• Full TypeScript types for both the parse output and the build/worksheet option shapes
• A bin CLI (node-xlsx) that reads a JSON worksheet payload from stdin and writes an .xlsx file

Common Use Cases

• Exporting database query results to a downloadable Excel report from an API endpoint
• Parsing user-uploaded .xlsx files into JSON for validation or import into a database
• Generating multi-sheet spreadsheets with custom column widths and merged header cells
• Scripting Excel file generation from the command line via the bundled CLI and stdin

Under The Hood

Architecture The library is a thin facade over SheetJS: src/index.ts exposes parse, parseMetadata, and build as pure functions that translate between node-xlsx’s simple {name, data} sheet shape and SheetJS’s native WorkBook/WorkSheet objects, src/workbook.ts supplies a minimal WorkBook class satisfying SheetJS’s type, src/config.ts wires Node’s fs module into SheetJS via set_fs so file-path reads and writes work outside the browser, and src/bin/cli.ts is a small stdin-driven wrapper around build(). There is no internal layering beyond this facade — if SheetJS’s own API shape changed, every call site here would need updating in lockstep.

Tech Stack Written in TypeScript 5.4 and built with tsup into dual CJS/ESM output plus declaration files, tested with Vitest, linted with ESLint and a shared config, and formatted with Prettier; the package manager is pnpm with a frozen lockfile enforced in CI. The single runtime dependency is the xlsx package itself, pulled directly from SheetJS’s own CDN tarball rather than the npm registry, since SheetJS no longer publishes every build there. There is no database or web framework involved — it is a pure file-processing library layered on Node’s fs module.

Code Quality A real test suite under test/specs exercises parsing, building, and edge cases (date fields, custom range functions, empty columns) against committed .xlsx/.json fixtures rather than mocks. Error handling is mostly implicit — parse and build let SheetJS’s own exceptions propagate uncaught. Naming is clear and consistent, types are exported for consumer use, and CI runs lint, Prettier, typecheck, and the full Vitest suite across multiple Node LTS versions plus a separate build-matrix job.

API Design The public surface is deliberately narrow — parse() and build() — trading SheetJS’s full object-model flexibility for arrays of arrays that most consumers actually want, while still allowing SheetJS’s raw cell notation (type, format, formula) for advanced cases. Getting started requires a single import and one function call, and the README documents every common scenario (buffer/file parsing, multi-sheet builds, column widths, merged ranges, primitive cell notation) with a runnable example.