Skip to content
Docs: Hypaxel for Node.js and browsersMenu

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.

Compatibilityv0.3.0 unreleased
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#

Install · npm
npm install hypaxel

Not 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, toBuffer and webStream load it themselves.
  • new Writer() and toBufferSync are synchronous, so call await init() once before them. Without it they throw an XlsxError that 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 as hypaxel/hypaxel_bg.wasm.
  • In workers and server runtimes that read the file from disk, initSync(bytes) loads it synchronously. Runtimes that import .wasm files 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#

APINode.jsBrowsers and WebAssembly runtimes
Writer, Worksheet, styles, tables, …✓✓ (after init())
drain(), finish(), toBuffer, toBufferSyncBufferUint8Array
webStream✓✓ (pull-based: rows are produced as the consumer reads)
toBlob✓
stream (Node Readable), writeFile✓
init, initSyncinit (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.

MethodPurpose
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: rowOutlineLevels declares the deepest grouping level up front, because Excel reads it before the rows. beginRow takes outlineLevel, hidden and collapsed.
  • Tables: columns must equal the header texts.

Options#

OptionDefaultMeaning
compressionLevel1Deflate level 0-9
sharedStringsfalseShared string table: smaller files for repeated text, more memory
flushThreshold65536Compressed bytes buffered before a chunk is produced
date1904falseUse 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')
cellReferencesfalseWrite 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: true if 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: bigint values are written as doubles, like every Excel number. NaN and infinities are written as #NUM!.
  • Dates: a Date is written as wall-clock time in the process time zone unless you set dates: '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.

Node.js: 100,000 and 1,000,000 rowsApple M1 Max, macOS 26.6; Node.js 22.23.2. Compared with ExcelJS 4.4.0.
100k rowslower is better
  1. Hypaxel, arrays, streamed133 ms, best
  2. Hypaxel, arrays, to buffer131 ms, best
  3. Hypaxel, objects, to buffer151 ms, 1.2×
  4. Hypaxel, WebAssembly engine, arrays, to buffer223 ms, 1.7×
  5. ExcelJS, streaming writer815 ms, 6.2×
  6. ExcelJS, in-memory workbook4,186 ms, 32×
Node.js: 100,000 and 1,000,000 rows
Case100k rowsPeak RSS (100k)1M rowsPeak RSS (1M)
Hypaxel, arrays, streamed133 ms87 MB1.23 s104 MB
Hypaxel, arrays, to buffer131 ms97 MB1.23 s204 MB
Hypaxel, objects, to buffer151 ms99 MB1.36 s207 MB
Hypaxel, WebAssembly engine, arrays, to buffer223 ms108 MB1.91 s271 MB
ExcelJS, streaming writer815 ms169 MB7.89 s612 MB
ExcelJS, in-memory workbook4,186 ms1,301 MBnot runnot run

Methodology and notes · Benchmark source

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.

Browsers: an XLSX Blob in headless ChromeApple M1 Max, macOS 26.6; Chrome 158.0.8127.36 (headless). Compared with SheetJS 0.20.3, ExcelJS 4.4.0.
100k rowslower is better
  1. Hypaxel (WebAssembly)153 ms, best
  2. SheetJS1,913 ms, 13×
  3. ExcelJS3,074 ms, 20×
Browsers: an XLSX Blob in headless Chrome
Case100k rowsFile (100k)300k rowsFile (300k)
Hypaxel (WebAssembly)153 ms5 MB484 ms15.2 MB
SheetJS1,913 ms15.1 MB7,099 ms45.5 MB
ExcelJS3,074 ms5.8 MB9,617 ms17.5 MB

Methodology and notes · Benchmark source

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