xlsx-kit spec

Getting started

This page walks the canonical xlsx-kit workflow: load a workbook, mutate it, write it back. Every snippet below is a real .ts file in this repo — svelte-check compiles them against the live xlsx-kit types on every build, so when this page renders, it’s already proven that the code typechecks.

Read, edit, write — full library

The top-level xlsx-kit entry gives you the full workbook model: cells, styles, charts, drawings, the lot. Pair it with the platform-specific I/O helpers from xlsx-kit/node (or your own XlsxSource).

site/src/lib/examples/basic-read-write.ts .ts
// Read an xlsx, mutate one cell, write it back.
//
// This file is imported as ?raw into the docs site so the snippet shown to
// readers is exactly what svelte-check / tsc compiled — if an API rename
// breaks this import, the docs build fails before deploy.

import { loadWorkbook, workbookToBytes } from 'xlsx-kit/io';
import { fromBuffer } from 'xlsx-kit/node';
import { setCell } from 'xlsx-kit/worksheet';
import { readFile, writeFile } from 'node:fs/promises';

const wb = await loadWorkbook(fromBuffer(await readFile('input.xlsx')));
const ref = wb.sheets[0];
if (ref?.kind === 'worksheet') {
  setCell(ref.sheet, 1, 1, 'Hello from xlsx-kit');
}
await writeFile('output.xlsx', await workbookToBytes(wb));

loadWorkbook returns a Workbook. wb.sheets is an array of { sheet, name, ... } records — the sheet property is the worksheet itself. Cell coordinates are 1-indexed (row=1, col=1 is A1) to match the openpyxl API.

workbookToBytes serializes back to a Uint8Array in one shot — fine for workbooks that fit in memory. For larger workbooks see Streaming.

Direct fs helpers (Node)

xlsx-kit/node exposes fromFile / toFile so you can skip the readFile / writeFile glue:

site/src/lib/examples/node-fs.ts .ts
// One-shot read + save direct from / to disk via the xlsx-kit/node
// helpers, no manual fs glue needed.

import { loadWorkbook, saveWorkbook } from 'xlsx-kit/io';
import { fromFile, toFile } from 'xlsx-kit/node';

const wb = await loadWorkbook(fromFile('input.xlsx'));
// ...mutate wb...
await saveWorkbook(wb, toFile('output.xlsx'));

fromFile returns an XlsxSource backed by a Node fs.ReadStream; toFile returns an XlsxSink backed by a fs.WriteStream. Both are streamed under the hood.

Browser via fetch

The streaming entry is browser-safe (no node:fs). Use fromResponse to consume a fetch Response straight into the loader without buffering the whole download:

site/src/lib/examples/browser-fetch.ts .ts
// Browser: pipe a fetch Response straight into the loader. fromResponse is
// streaming, so the workbook starts parsing before the download is done.

import { fromResponse, loadWorkbook } from 'xlsx-kit/io';

const response = await fetch('/sheet.xlsx');
const wb = await loadWorkbook(fromResponse(response));
const ref = wb.sheets[0];
if (ref?.kind === 'worksheet') {
  console.log(ref.sheet.title);
}

This works in any environment with fetch + Web Streams: modern browsers, Bun, Deno, Cloudflare Workers, edge runtimes.

What’s next