Getting Started

Getting Started

Installation

npm install modern-xlsx
# or
pnpm add modern-xlsx
# or
yarn add modern-xlsx

Requires a runtime with WASM support: Node.js 24+, Bun, Deno, or modern browsers.

Initialize WASM

Before any operation, initialize the WASM module once:

import { initWasm } from 'modern-xlsx';
await initWasm();

This loads and compiles the ~939 KB WASM binary. Call it once at application startup.

Create a Workbook

import { Workbook } from 'modern-xlsx';

const wb = new Workbook();
const ws = wb.addSheet('Sheet1');

// Set values
ws.cell('A1').value = 'Name';
ws.cell('B1').value = 'Age';
ws.cell('A2').value = 'Alice';
ws.cell('B2').value = 30;

Apply Styles

const headerStyle = wb.createStyle()
  .font({ bold: true, size: 12, color: '1F4E79' })
  .fill({ pattern: 'solid', fgColor: 'D6E4F0' })
  .alignment({ horizontal: 'center' })
  .build(wb.styles);

ws.cell('A1').styleIndex = headerStyle;
ws.cell('B1').styleIndex = headerStyle;

Write to File

// Node.js / Bun / Deno
await wb.toFile('output.xlsx');

// Any environment (returns Uint8Array)
const buffer = await wb.toBuffer();

// Browser (returns Blob)
import { writeBlob } from 'modern-xlsx';
const blob = writeBlob(wb);

Read a File

import { readFile, readBuffer } from 'modern-xlsx';

// From file path
const wb = await readFile('data.xlsx');

// From buffer
const wb = await readBuffer(uint8Array);

// Access data
const ws = wb.getSheet('Sheet1');
console.log(ws?.cell('A1').value);

---

Browser & CDN Usage

modern-xlsx ships a self-contained IIFE browser bundle (modern-xlsx.min.js, ~29 KB) that exposes the full API on window.ModernXlsx. No bundler required.

jsDelivr

<script src="https://cdn.jsdelivr.net/npm/modern-xlsx@0.3.0/dist/modern-xlsx.min.js"></script>
<script>
  (async () => {
    await ModernXlsx.initWasm();

    const wb = new ModernXlsx.Workbook();
    const ws = wb.addSheet('Sheet1');
    ws.cell('A1').value = 'Hello from CDN!';

    const blob = ModernXlsx.writeBlob(wb);
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'hello.xlsx';
    a.click();
    URL.revokeObjectURL(url);
  })();
</script>

unpkg

<script src="https://unpkg.com/modern-xlsx@0.3.0/dist/modern-xlsx.min.js"></script>

WASM Auto-Detection

The IIFE bundle automatically detects the correct WASM binary URL using detectWasmUrl(). It derives the URL relative to the script's src attribute, so the .wasm file is loaded from the same CDN path as the .js file — no manual configuration needed.

If you self-host the files, place modern-xlsx.wasm alongside modern-xlsx.min.js:

/static/
  modern-xlsx.min.js
  modern-xlsx.wasm

Initialization Modes

// Async init (recommended for browsers)
await ModernXlsx.initWasm();

// Async init with custom WASM URL
await ModernXlsx.initWasm('https://my-cdn.example.com/modern-xlsx.wasm');

// Synchronous init from pre-loaded buffer (Node.js / tests)
const wasmBytes = fs.readFileSync('modern-xlsx.wasm');
ModernXlsx.initWasmSync(wasmBytes);

// Lazy auto-init on first use
await ModernXlsx.ensureReady();

---

Web Worker Setup

For large files, offload XLSX processing to a Web Worker to keep the UI responsive:

<script src="https://cdn.jsdelivr.net/npm/modern-xlsx@0.3.0/dist/modern-xlsx.min.js"></script>
<script type="module">
  const worker = ModernXlsx.createXlsxWorker({
    workerUrl: 'https://cdn.jsdelivr.net/npm/modern-xlsx@0.3.0/dist/modern-xlsx.worker.js',
  });

  // Read file in worker thread
  const input = document.querySelector('input[type="file"]');
  input.addEventListener('change', async (e) => {
    const file = e.target.files[0];
    const buffer = new Uint8Array(await file.arrayBuffer());
    const data = await worker.readBuffer(buffer);
    console.log('Sheets:', Object.keys(data.sheets));
  });

  // Clean up when done
  // worker.terminate();
</script>

The worker script (modern-xlsx.worker.js) initializes WASM internally on first use. All parsing and serialization run off the main thread.

---

Next Steps

• Styling Guide — Full styling reference
• API Reference — Complete API docs
• Examples — Browser, Web Worker, and framework examples
• Performance — Optimization tips

Browser & CDN

Use modern-xlsx directly in the browser with a single script tag — no bundler required:

<script src="https://cdn.jsdelivr.net/npm/modern-xlsx@0.3.0/dist/modern-xlsx.min.js"></script>
<script>
  (async () => {
    await ModernXlsx.initWasm();
    const wb = new ModernXlsx.Workbook();
    wb.addSheet('Sheet1').cell('A1').value = 'Hello from CDN!';
    const blob = ModernXlsx.writeBlob(wb);
    // trigger download...
  })();
</script>

Also available via unpkg: https://unpkg.com/modern-xlsx@0.3.0/dist/modern-xlsx.min.js

The IIFE bundle (29 KB gzipped: 10 KB) exposes the full API on window.ModernXlsx. The WASM binary is automatically fetched from the same CDN path.

Custom WASM URL

For environments where auto-detection doesn't work:

await ModernXlsx.initWasm('https://my-cdn.com/modern-xlsx.wasm');

Web Worker

Keep the main thread responsive by running XLSX operations in a Web Worker:

import { createXlsxWorker } from 'modern-xlsx';

const worker = createXlsxWorker({
  workerUrl: '/modern-xlsx.worker.js',
  wasmUrl: '/modern-xlsx.wasm',  // optional
});

// Read XLSX in worker thread
const data = await worker.readBuffer(xlsxBytes);

// Write XLSX in worker thread
const output = await worker.writeBuffer(workbookData);

// Clean up
worker.terminate();

The worker script (modern-xlsx.worker.js) auto-initializes WASM on first use. Both readBuffer and writeBuffer return Promises and use transferable ArrayBuffers for zero-copy data transfer.

Lazy Initialization

Auto-initialize WASM on first use:

import { ensureReady, Workbook } from 'modern-xlsx';
await ensureReady();  // no-op if already initialized