Skip to content
Docs: Getting startedMenu

Getting started

Install Hypaxel, write a first XLSX workbook, stream an Excel download from a web endpoint or the browser, and read a workbook back row by row.

v0.3.0 unreleasedLast updated View as Markdown

This page takes you from choosing an implementation to a first workbook, a streamed HTTP download and a first read. Each language has its own guide with the full details; the examples here are the shortest working path.

Choose your language#

LanguagePackageRuntimeEngineReadsGuide
.NETHypaxel, Hypaxel.AspNetCore.NET 8, 9, 10, 11nativeyes/docs/dotnet
Rusthypaxel, hypaxel-axumRust 1.85+nativeyes/docs/rust
PythonhypaxelCPython 3.10+Rust core (PyO3)yes/docs/python
Node.jshypaxelNode.js 22+Rust core (napi-rs)not yet/docs/nodejs
BrowsershypaxelChrome/Edge 96+, Firefox 79+, Safari 15+Rust core (WebAssembly)not yet/docs/nodejs#browsers
Gogithub.com/vensas/hypaxel/goGo 1.26+nativeyes/docs/go
Javade.vensas:hypaxelJava 17+nativeyes/docs/java
PHPvensas/hypaxelPHP 8.2+ (64-bit, ext-zlib)nativenot yet/docs/php

The Python and Node.js packages call into the Rust core; in browsers, the Node.js package runs the same core as WebAssembly. The other five are independent implementations of the same design, so each runs without native libraries or extra runtime dependencies.

Install#

  • .NET: packages Hypaxel (core writer) and Hypaxel.AspNetCore (HTTP response helpers).
  • Rust: crates hypaxel (core writer) and hypaxel-axum (axum response type).
pip install hypaxel                        # Python
npm install hypaxel                        # Node.js
go get github.com/vensas/hypaxel/go        # Go
composer require vensas/hypaxel            # PHP

Java (Maven coordinates):

<dependency>
  <groupId>de.vensas</groupId>
  <artifactId>hypaxel</artifactId>
  <version>0.3.0</version>
</dependency>

Your first workbook#

Each example writes a list of orders to orders.xlsx. Where the language supports object or record mapping, the sheet gets a styled, frozen header row and an auto filter automatically.

.NET#

using Hypaxel;

await using var writer = XlsxWriter.Create("orders.xlsx");
await writer.WriteWorksheetAsync("Orders", orders);
await writer.CompleteAsync();

Rust#

let file = std::io::BufWriter::new(std::fs::File::create("orders.xlsx")?);
let mut writer = XlsxWriter::new(file);
writer.write_sheet_records("Orders", &orders)?;   // any T: Serialize
writer.finish()?;

Python#

import hypaxel

hypaxel.to_xlsx(orders, "orders.xlsx")    # list of dicts / dataclasses / models, or a DataFrame

Node.js#

import { writeFile } from 'hypaxel'

await writeFile('orders.xlsx', orders)

Browser#

The same package runs in browsers on WebAssembly; bundlers pick that build automatically.

import { toBlob } from 'hypaxel'

const blob = await toBlob(orders, { sheetName: 'Orders' })
const link = Object.assign(document.createElement('a'), { href: URL.createObjectURL(blob), download: 'orders.xlsx' })
link.click()
URL.revokeObjectURL(link.href)

See Browsers for loading the WebAssembly module and streaming large exports.

Go#

w := hypaxel.NewWriter(file)
if err := hypaxel.WriteSheet(w, "Orders", orders); err != nil {
	return err
}
return w.Close()

Java#

try (XlsxWriter writer = XlsxWriter.create(Path.of("orders.xlsx"))) {
    writer.writeWorksheet("Orders", Order.class, orders);
}

PHP#

use Vensas\Hypaxel\Xlsx;

Xlsx::writeFile('orders.xlsx', $orders);

Streaming a web response#

The main use case is an export endpoint that streams the workbook while rows are read from the database. The client starts receiving bytes immediately, and memory per request stays bounded.

ASP.NET Core#

app.MapGet("/orders.xlsx", (AppDb db) =>
    Results.Extensions.Excel(db.Orders.AsNoTracking().AsAsyncEnumerable(), "orders"));

axum#

async fn orders(State(pool): State<PgPool>) -> Xlsx {
    Xlsx::from_stream("Orders", sqlx::query_as::<_, Order>("SELECT ...").fetch(&pool)).filename("orders.xlsx")
}

FastAPI#

from hypaxel.starlette import XlsxResponse

@app.get("/orders.xlsx")
async def orders():
    return XlsxResponse(hypaxel.astream_records(fetch_orders()), filename="orders.xlsx")

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)
})

Go net/http#

http.Handle("/orders.xlsx", hypaxelhttp.Handler("orders", func(r *http.Request, w *hypaxel.Writer) error {
	return hypaxel.WriteSheetSeq2(w, "Orders", db.Orders(r.Context()))
}))

Spring MVC#

StreamingResponseBody body = out -> {
    try (XlsxWriter writer = XlsxWriter.create(out); Stream<Order> orders = repository.streamAll()) {
        writer.writeWorksheet("Orders", Order.class, orders);
    }
};

PHP#

Xlsx::download('orders.xlsx', $pdo->query('SELECT id, customer, amount FROM orders', PDO::FETCH_ASSOC));

Reading a workbook#

The readers in .NET, Rust, Python, Go and Java return rows one at a time, with memory bounded by the shared strings plus one row. Dates, times and durations are recognised from number formats. Node.js and PHP do not read yet.

.NET#

using var reader = XlsxReader.Open("orders.xlsx");
using var rows = reader.OpenWorksheet("Orders");
while (rows.Read())
{
    var row = rows.Row;
    if (row.TryGetString(1, out var customer) && row.TryGetDouble(3, out var amount))
        Console.WriteLine($"{row.Number}: {customer} {amount}");
}

Rust#

let mut reader = hypaxel::XlsxReader::open("orders.xlsx")?;
let mut rows = reader.worksheet("Orders")?;
while let Some(row) = rows.next_row()? {
    let amount = row.get(3).as_f64();
}

Python#

for row in hypaxel.iter_rows("orders.xlsx", "Orders"):
    print(row)

df = hypaxel.read_dataframe("orders.xlsx")    # pandas; library="polars" for polars

Go#

r, err := hypaxel.OpenReader("orders.xlsx")
if err != nil {
	return err
}
defer r.Close()
rows, err := r.Rows("Orders")
if err != nil {
	return err
}
defer rows.Close()
for rows.Next() {
	amount := rows.Row().Get(3)
	_ = amount
}
return rows.Err()

Java#

try (XlsxReader reader = XlsxReader.open(Path.of("orders.xlsx"));
     SheetReader rows = reader.worksheet("Orders")) {
    for (Row row = rows.nextRow(); row != null; row = rows.nextRow()) {
        System.out.println(row.getString(1) + " " + row.getNumber(3));
    }
}

Columns are 1-based in every reader, and rows without values are skipped. Each language guide covers values, errors and limits for untrusted input: .NET, Rust, Python, Go, Java.

Key constraints#

When writing, Hypaxel never goes back to rewrite earlier parts of the file. That is what keeps memory constant, and it sets a few rules:

  • Write order. Rows are written top to bottom and cells left to right. To leave gaps, skip cells or rows, or begin a row at a later row number.
  • One sheet at a time. Adding a worksheet completes the previous one. You cannot return to an earlier sheet.
  • Sheet options up front. Column definitions, frozen panes and the row outline depth go into the worksheet options when you create the sheet, because they come before the cell data in the file. Merged cells, auto filters and tables can be added at any time before the sheet completes. Auto-fit columns are the exception that measures data first: the sheet’s output is held back for a sample of rows.
  • Formulas without cached results. Formulas are stored without a computed value. Excel recalculates them when the file opens.