Troubleshooting and FAQ

The library fails while loading in a browser

An error containing WebAssembly compilation failed usually means the runtime has no usable WebAssembly support or CSP blocks compilation. Allow 'wasm-unsafe-eval' in script-src. See Browsers and CSP. There is no JavaScript fallback engine.

Named ESM imports fail

Use a default import:

app.mjs

import XLSX from "@agent-sheet/wasm";
const ws = XLSX.utils.aoa_to_sheet([[1, 2]]);

This is ESM usage, not browser-global syntax. Node named imports such as import { utils } from "@agent-sheet/wasm" are not supported.

Styles disappeared

Pass cellStyles: true when reading and writing. For XLS and XLSB rich text, also pass bookSST: true when writing. Check Cell styles and Known differences for format limitations.

Charts or print settings disappeared

Normal read-edit-write creates a new file from the JavaScript workbook model. Use template mode to preserve file content that the model does not represent. Use template: true for both the read and the write.

Browser disk helpers fail

Use a file input and File.arrayBuffer(), then call read. Browser code cannot use readFile on an arbitrary disk path. writeFile triggers a download in supported browsers.

A mini-build function or format fails

The mini build has fewer formats and no stream namespace. Use the full build when you need the complete format set. See Supported formats.

Does it calculate formulas?

Do not treat the package as a spreadsheet calculation application. Store formula text in f and a cached result in v when you need one. Template mode can mark a workbook for recalculation when it is later opened; see Template editing.

Why does memory stay high after a large file?

WebAssembly linear memory grows and cannot shrink. Later operations can reuse it. Workbook objects also use JavaScript memory. End a dedicated worker when you want to release its realm. See Large files and performance.

Inspect the runtime

The public diagnostics hook provides a snapshot:

const XLSX = require("@agent-sheet/wasm");
const stats = XLSX[Symbol.for("agent-sheet.runtime")].stats();
require("node:assert/strict").equal(stats.instances, 1);
require("node:assert/strict").ok(stats.memoryBytes > 0);

instances reports the instance count. memoryBytes reports the current WebAssembly linear memory size in bytes. Additional diagnostic counters in the snapshot are not workbook counts or total process memory. Do not use them as application limits.

Do I need an initialization or disposal step?

No. The engine is ready when the package loads. Workbooks are plain JavaScript objects. There is no workbook disposal call. Spreadsheet operations are synchronous, while writeFileAsync provides asynchronous disk output after serialization.

Which applications and browsers were tested?

Node 22 and 24, Chromium and Firefox pages and Web Workers, esbuild bundles, AMD, and the script global were tested. Safari, Node below 22, and opening files in Excel or Apple Numbers were not tested.