Hypaxel for Node.js and browsers
Stream Excel (XLSX) files from Node.js with flat memory and backpressure, or build them in the browser with the same API on WebAssembly.
v0.3.0 unreleasedLast updated View as Markdown
Generating large Excel files in Node.js tends to grow the heap with every row and block the response until the workbook is complete. Hypaxel for Node.js writes .xlsx files as a forward-only stream instead: rows are serialized and compressed in the Hypaxel Rust core (native code through napi-rs) as you write them, so memory stays flat whether you export 10 rows or a million, and a download can start while your query is still running. It returns a Node Readable or a web ReadableStream, and backpressure from the client pauses your data source.
The same package runs in browsers: there the engine is compiled to WebAssembly (171 KB gzipped) and keeps the same API, so you can build a workbook client-side and hand it to the user as a download. See Browsers.
- Package
- hypaxel
- Requires
- Node.js 22+; browsers with WebAssembly (Chrome/Edge 96+, Firefox 79+, Safari 15+)
- Engine
- Rust core via napi-rs (Node.js) and WebAssembly (browsers)
- Web
- stream() for Express, Fastify, Koa; webStream() for Next.js, Hono; toBlob() for browser downloads
- Registry
- npm (not published yet)
- License
- Apache-2.0
Install#
npm install hypaxelNot published yethypaxel is not on npm yet. The command above is what installation will look like once it is.
The package is not published yet. Until then, build it from source: see Building from source. It requires Node.js 22 or later, or a browser with WebAssembly (every current browser). It is written in strict TypeScript, ships its own type declarations and works from ESM and CommonJS.
Quick start#
import { toBuffer, writeFile } from 'hypaxel'
const orders = [
{ id: 1, customer: 'Ada', amount: 1234.5, created: new Date() },
{ id: 2, customer: 'Linus', amount: 99.99, created: new Date() },
]
await writeFile('orders.xlsx', orders)
const buffer = await toBuffer(orders, {
sheetName: 'Orders',
columns: ['id', { key: 'customer', header: 'Customer', width: 30 }, { key: 'amount', numFormat: '#,##0.00' }],
})Objects get a styled, frozen header row and an auto filter. columns selects and orders the properties; without it the keys of the first object are used. Arrays are written as plain rows:
await writeFile('matrix.xlsx', [[1, 'a'], [2, 'b']], { columns: ['Id', 'Label'] })Supported values#
number, string, boolean, Date, bigint and formulas. null, undefined and invalid dates become empty cells.
Streaming HTTP responses#
stream() consumes its source lazily and yields the file in chunks. The source can be any iterable or async iterable: an array, a generator, a database cursor, a Readable in object mode.
Express#
import { CONTENT_TYPE, stream } from 'hypaxel'
import { pipeline } from 'node:stream/promises'
app.get('/orders.xlsx', async (req, res) => {
res.setHeader('Content-Type', CONTENT_TYPE)
res.setHeader('Content-Disposition', 'attachment; filename="orders.xlsx"')
await pipeline(stream(db.orders.cursor()), res)
})Fastify#
fastify.get('/orders.xlsx', (request, reply) =>
reply.header('Content-Type', CONTENT_TYPE).send(stream(db.orders.cursor())))Next.js route handlers, Hono and other Response-based frameworks#
import { CONTENT_TYPE, webStream } from 'hypaxel'
export function GET() {
return new Response(webStream(fetchOrders()), { headers: { 'Content-Type': CONTENT_TYPE } })
}Browsers#
The same import ... from 'hypaxel' resolves to the WebAssembly build in browser bundles: Vite, webpack, esbuild, Rollup and other bundlers honor the browser export condition. Node.js, Deno and Bun resolve the node condition and load the native module. Any other runtime gets the WebAssembly build through the default condition, and import ... from 'hypaxel/wasm' selects it explicitly everywhere.
import { toBlob } from 'hypaxel'
const blob = await toBlob(rows, { columns: ['id', { key: 'amount', numFormat: '#,##0.00' }] })
const link = Object.assign(document.createElement('a'), { href: URL.createObjectURL(blob), download: 'orders.xlsx' })
link.click()
URL.revokeObjectURL(link.href)Loading the WebAssembly module#
The module (hypaxel_bg.wasm) is loaded on first use:
toBlob,toBufferandwebStreamload it themselves.new Writer()andtoBufferSyncare synchronous, so callawait init()once before them. Without it they throw anXlsxErrorthat says so.- By default the module is fetched from next to the JavaScript file, which bundlers resolve and copy. To serve it from elsewhere (a CDN, a strict Content Security Policy), pass its URL or bytes:
await init('/assets/hypaxel_bg.wasm'). The file is exported ashypaxel/hypaxel_bg.wasm. - In workers and server runtimes that read the file from disk,
initSync(bytes)loads it synchronously. Runtimes that import.wasmfiles as compiled modules (Cloudflare Workers, for example) can pass the module:import wasm from 'hypaxel/hypaxel_bg.wasm'; await init(wasm).
init() also exists in Node.js, where it resolves immediately, so shared code can call it unconditionally.
What is available where#
| API | Node.js | Browsers and WebAssembly runtimes |
|---|---|---|
Writer, Worksheet, styles, tables, … | ✓ | ✓ (after init()) |
drain(), finish(), toBuffer, toBufferSync | Buffer | Uint8Array |
webStream | ✓ | ✓ (pull-based: rows are produced as the consumer reads) |
toBlob | ✓ | |
stream (Node Readable), writeFile | ✓ | |
init, initSync | init (no-op) | ✓ |
Large exports in the browser#
webStream keeps memory bounded when its consumer writes to disk, for example through the File System Access API (showSaveFilePicker() and pipeTo). toBlob holds the finished file in memory, compressed.
Browser support#
The module uses the WebAssembly extensions Rust enables by default (reference types, bulk memory, multi-value, sign extension, non-trapping float-to-int), so it needs Chrome/Edge 96+, Firefox 79+ or Safari 15+ (all from 2021). It does not use SIMD, which would raise the Safari minimum to 16.4 for about 8% more speed.
The native and WebAssembly engines are the same Rust code and produce byte-identical files; the test suite checks this.
Full control with Writer#
import { Formula, Styled, Writer } from 'hypaxel'
import { writeFileSync } from 'node:fs'
const workbook = new Writer()
const header = workbook.addStyle({ bold: true, fontColor: '#FFFFFF', fill: '#305496', align: 'center' })
const money = workbook.addStyle({ numFormat: '#,##0.00' })
const sheet = workbook.addWorksheet('Sales', { freezeRows: 1, columnWidths: [20, 12, 14] })
sheet.writeRow(['Product', 'Date', 'Revenue'], header)
sheet.writeRows([
['Widget', new Date(2024, 4, 1), new Styled(1234.5, money)],
['Gadget', new Date(2024, 4, 2), new Styled(99.99, money)],
])
sheet.writeRow(['Total', null, new Styled(new Formula('SUM(C2:C3)'), money)])
writeFileSync('report.xlsx', workbook.finish())A Writer keeps its output in memory. finish() returns what is left; to keep memory flat while writing a large workbook yourself, take the bytes produced so far with drain() between batches of rows and send them on.
Worksheets are written one at a time: adding a worksheet completes the previous one.
| Method | Purpose |
|---|---|
writeRow(values, style?) | One row. style applies to cells without their own |
writeRows(rows, style?) | Many rows; returns the count |
writeRecords(records, keys, styles?) | One row per object, taking keys in order |
write(value, style?), endRow() | Cell-by-cell writing |
beginRow({ height, style, outlineLevel, hidden, collapsed }) | Start a row with row properties; the next writeRow fills it |
skipCells(n), skipRows(n) | Leave cells or rows empty |
mergeCells(r1, c1, r2, c2), autofilter(r1, c1, r2, c2) | Ranges, 1-based and inclusive |
addTable(r1, c1, r2, c2, { columns, name, style, ... }) | Excel table; columns must equal the header texts |
Object mapping#
The export helpers (stream, webStream, toBuffer, toBufferSync, writeFile) take plain objects and write one row per object. columns controls which properties are written, in which order, and how:
- a string selects a property by key;
- an object such as
{ key: 'customer', header: 'Customer', width: 30 }or{ key: 'amount', numFormat: '#,##0.00' }sets the header text, column width or number format.
Inside a Writer, writeRecords(records, keys, styles?) writes one row per object, taking keys in order.
Tables, row grouping and auto-fit#
const sheet = writer.addWorksheet('Regions', { autofit: true, rowOutlineLevels: 1, outlineSummaryAbove: true })
sheet.writeRow(['Region', 'Revenue'])
sheet.writeRow(['North', 300])
sheet.beginRow({ outlineLevel: 1 })
sheet.writeRow(['Store A', 120])
sheet.addTable(1, 1, sheet.row, 2, { name: 'Regions', columns: ['Region', 'Revenue'], style: 'TableStyleMedium9' })- Auto-fit:
autofit(or{ sampleRows, maxWidth }) holds back the sheet’s output until the sample (default 1,000 rows, at most 8 MiB of XML) has been measured, then streams as usual. - Row grouping:
rowOutlineLevelsdeclares the deepest grouping level up front, because Excel reads it before the rows.beginRowtakesoutlineLevel,hiddenandcollapsed. - Tables:
columnsmust equal the header texts.
Options#
| Option | Default | Meaning |
|---|---|---|
compressionLevel | 1 | Deflate level 0-9 |
sharedStrings | false | Shared string table: smaller files for repeated text, more memory |
flushThreshold | 65536 | Compressed bytes buffered before a chunk is produced |
date1904 | false | Use the 1904 date system |
dates | 'local' | Excel has no time zones. A Date is written as wall-clock time in the process time zone ('local') or in UTC ('utc') |
cellReferences | false | Write a reference such as B7 on every cell |
Export helpers (stream, webStream, toBuffer, toBufferSync, writeFile) also take sheetName, columns, header, autofilter and batchRows.
Notes and limits#
- ExcelJS as a reader: by default Hypaxel omits cell references that follow from a cell’s position. That is valid and is read by Excel, LibreOffice, openpyxl and calamine, but ExcelJS fails on such files. Pass
cellReferences: trueif your files are read with ExcelJS. - Excel limits apply: 1,048,576 rows, 16,384 columns and 32,767 characters per cell. Exceeding them throws an
XlsxError. - Numbers:
bigintvalues are written as doubles, like every Excel number.NaNand infinities are written as#NUM!. - Dates: a
Dateis written as wall-clock time in the process time zone unless you setdates: 'utc'. - Styles belong to the writer that created them.
- One call per batch: cells are encoded into a compact buffer in JavaScript and handed to the engine in batches, so there is no native or WebAssembly call per cell.
Performance#
On an Apple M1 Max with Node.js 22, Hypaxel writes 100,000 rows × 10 columns in about 0.13 s and 1 million rows in about 1.2 s. That is about 6 times faster than ExcelJS’s streaming writer and 30 times faster than an in-memory ExcelJS workbook, with a much lower peak RSS. The WebAssembly engine, run in Node.js for comparison, is about 1.5 times slower than the native module, which is why Node.js uses the native one.
- Hypaxel, arrays, streamed133 ms, best
- Hypaxel, arrays, to buffer131 ms, best
- Hypaxel, objects, to buffer151 ms, 1.2×
- Hypaxel, WebAssembly engine, arrays, to buffer223 ms, 1.7×
- ExcelJS, streaming writer815 ms, 6.2×
- ExcelJS, in-memory workbook4,186 ms, 32×
| Case | 100k rows | Peak RSS (100k) | 1M rows | Peak RSS (1M) |
|---|---|---|---|---|
| Hypaxel, arrays, streamed | 133 ms | 87 MB | 1.23 s | 104 MB |
| Hypaxel, arrays, to buffer | 131 ms | 97 MB | 1.23 s | 204 MB |
| Hypaxel, objects, to buffer | 151 ms | 99 MB | 1.36 s | 207 MB |
| Hypaxel, WebAssembly engine, arrays, to buffer | 223 ms | 108 MB | 1.91 s | 271 MB |
| ExcelJS, streaming writer | 815 ms | 169 MB | 7.89 s | 612 MB |
| ExcelJS, in-memory workbook | 4,186 ms | 1,301 MB | not run | not run |
Browsers#
In headless Chrome on the same machine, Hypaxel’s WebAssembly build turns 100,000 rows into an XLSX Blob in about 0.15 s, about 12 times faster than SheetJS and 20 times faster than ExcelJS. Its WebAssembly memory stayed at 2.4 MB. The browser does not expose the peak JavaScript heap, so memory is not compared across libraries.
- Hypaxel (WebAssembly)153 ms, best
- SheetJS1,913 ms, 13×
- ExcelJS3,074 ms, 20×
| Case | 100k rows | File (100k) | 300k rows | File (300k) |
|---|---|---|---|---|
| Hypaxel (WebAssembly) | 153 ms | 5 MB | 484 ms | 15.2 MB |
| SheetJS | 1,913 ms | 15.1 MB | 7,099 ms | 45.5 MB |
| ExcelJS | 3,074 ms | 5.8 MB | 9,617 ms | 17.5 MB |
See Performance for methodology and reproduction, and Benchmarks for the full tables.
Building from source#
The source is at github.com/vensas/hypaxel, in the node/ directory. Report bugs at github.com/vensas/hypaxel/issues.
Requires Node.js 22+, a Rust toolchain (1.88+) with the wasm32-unknown-unknown target, and wasm-bindgen-cli matching the wasm-bindgen version in wasm/Cargo.toml.
rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli --version 0.2.130 --locked
cd node
npm install
npm run build # native addon (napi-rs), WebAssembly module (wasm-bindgen) and TypeScript
npm test # both engines, in Node.js
npm run test:browser # the WebAssembly build in headless Chrome