@worksheet-js/excel

High-performance spreadsheet I/O engine for XLSX, CSV, JSON, and HTML.

@worksheet-js/excel is an industrial-grade I/O engine for reading and writing spreadsheet data. It handles complex OpenXML parsing for XLSX files and provides a unified API for CSV, TSV, JSON, and HTML formats. Works in both browser and Node.js environments — no DOM dependency required.

Table of Contents

• Key Features
• Installation
• License Initialization
• Quick Start
• Usage
  • Loading XLSX (Browser)
  • Loading XLSX (Node.js)
  • Loading CSV
  • Loading JSON
  • Loading HTML
  • Exporting XLSX
  • Exporting CSV
  • Browser Download
• Public API
  • WorkbookLoader
  • WorkbookExporter
• Parsed Data Shape
• Style Extraction
• License

Key Features

• Native XLSX Support — Optimized OpenXML reader using fast-xml-parser and fflate for decompression.
• High-Fidelity Style Preservation — Extracts fonts, fills, borders, number formats, alignment, and text direction.
• Advanced Cell Features — Merged cells, conditional formatting rules, data validations, and hyperlinks.
• Multi-Format I/O — Unified API for XLSX, CSV/TSV, JSON, and HTML <table> extraction.
• Browser & Node.js — No DOM dependency; works server-side for headless report generation.
• Large File Handling — Handles workbooks with 100,000+ rows at a low memory footprint.

Installation

npm install @worksheet-js/excel
# or
pnpm add @worksheet-js/excel
# or
yarn add @worksheet-js/excel

No peer dependencies required. fflate and fast-xml-parser are bundled as regular dependencies.

License Initialization

@worksheet-js/excel is proprietary software. Initialize your license key before calling any WorkbookLoader or WorkbookExporter methods.

import { initializeLicense } from '@worksheet-js/excel';

// Call once at application startup
initializeLicense('YOUR-LICENSE-KEY');

To obtain a license key, contact [email protected].

Quick Start

import { WorkbookLoader, initializeLicense } from '@worksheet-js/excel';

initializeLicense('YOUR-LICENSE-KEY');

// Parse an XLSX file
const buffer = new Uint8Array(await file.arrayBuffer());
const { result, meta } = await WorkbookLoader.loadFromBuffer(buffer);

const sheets = result.workbook.sheets;
console.log(
  'Sheets:',
  sheets.map((s) => s.name)
);
console.log('Parse time:', meta.parseTimeMs, 'ms');

// Access cell data
const firstSheet = sheets[0];
const cellA1 = firstSheet.cells[0][0]; // [row][col]
console.log('A1 value:', cellA1.value);
console.log('A1 style:', cellA1.style);

Usage

Loading XLSX (Browser)

import { WorkbookLoader } from '@worksheet-js/excel';

const fileInput = document.querySelector<HTMLInputElement>('#file')!;

fileInput.addEventListener('change', async () => {
  const file = fileInput.files![0];
  const buffer = await file.arrayBuffer();
  const { result, meta } = await WorkbookLoader.loadFromBuffer(new Uint8Array(buffer));

  console.log('Sheet count:', result.workbook.sheets.length);
  console.log(
    'Sheet names:',
    result.workbook.sheets.map((s) => s.name)
  );
  console.log('Parse time:', meta.parseTimeMs, 'ms');
});

Loading XLSX (Node.js)

import { readFileSync } from 'fs';
import { WorkbookLoader } from '@worksheet-js/excel';

const buffer = new Uint8Array(readFileSync('report.xlsx'));
const { result } = await WorkbookLoader.loadFromBuffer(buffer);

// Iterate sheets
for (const sheet of result.workbook.sheets) {
  console.log(`Sheet: ${sheet.name}, rows: ${sheet.cells.length}`);
}

Loading CSV

import { WorkbookLoader } from '@worksheet-js/excel';

const csvText = `Name,Age,City\nAlice,30,NYC\nBob,25,LA`;

const { result } = await WorkbookLoader.loadFromCsvBuffer(csvText, {
  delimiter: ',',
  hasHeader: true,
});

const rows = result.workbook.sheets[0].cells;
console.log(rows[0].map((c) => c.value)); // ['Alice', 30, 'NYC']

Loading JSON

import { WorkbookLoader } from '@worksheet-js/excel';

const data = [
  { product: 'Widget A', revenue: 15_000, units: 300 },
  { product: 'Widget B', revenue: 22_000, units: 450 },
];

const { result } = await WorkbookLoader.loadFromJsonBuffer(JSON.stringify(data));

Loading HTML

import { WorkbookLoader } from '@worksheet-js/excel';

const html = `
  <table>
    <tr><th>Name</th><th>Score</th></tr>
    <tr><td>Alice</td><td>95</td></tr>
    <tr><td>Bob</td><td>87</td></tr>
  </table>
`;

const { result } = await WorkbookLoader.loadFromHtmlBuffer(html);

Exporting XLSX

import { WorkbookExporter } from '@worksheet-js/excel';

// Generate a Uint8Array — use for upload, IndexedDB, Node.js file write, etc.
const buffer = await WorkbookExporter.exportToBuffer(spreadsheetInstance);

// In Node.js
import { writeFileSync } from 'fs';
writeFileSync('output.xlsx', buffer);

// In the browser — create a Blob
const blob = new Blob([buffer], {
  type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
});
const url = URL.createObjectURL(blob);

Exporting CSV

import { WorkbookExporter } from '@worksheet-js/excel';

// Export the active sheet (default) as a CSV string
const csv = WorkbookExporter.exportToCsv(spreadsheetInstance);

// Export a specific sheet by zero-based index
const sheet2Csv = WorkbookExporter.exportToCsv(spreadsheetInstance, 1);

Browser Download

import { WorkbookExporter } from '@worksheet-js/excel';

// Trigger a Save As dialog in the browser
await WorkbookExporter.download(spreadsheetInstance, 'xlsx', 'Q4-Report.xlsx');
await WorkbookExporter.download(spreadsheetInstance, 'csv', 'data.csv');

Public API

WorkbookLoader

All methods are static and return a Promise.

class WorkbookLoader {
  /**
   * Parse an XLSX file from a binary buffer.
   * @param buffer - Raw XLSX bytes as Uint8Array
   */
  static loadFromBuffer(buffer: Uint8Array): Promise<{
    result: ParsedWorkbook;
    meta: { parseTimeMs: number; sheetCount: number };
  }>;

  /**
   * Parse CSV or TSV data.
   * @param buffer - CSV/TSV text or Uint8Array
   * @param options - Delimiter, header detection, and encoding options
   */
  static loadFromCsvBuffer(
    buffer: Uint8Array | string,
    options?: CsvOptions
  ): Promise<{ result: ParsedWorkbook }>;

  /**
   * Parse structured JSON into a workbook.
   * Supports arrays of objects; keys become column headers.
   * @param buffer - JSON string or Uint8Array
   * @param options - Column mapping and header generation options
   */
  static loadFromJsonBuffer(
    buffer: Uint8Array | string,
    options?: JsonOptions
  ): Promise<{ result: ParsedWorkbook }>;

  /**
   * Extract data from HTML <table> elements.
   * @param buffer - HTML string or Uint8Array
   * @param options - Table selector and header row options
   */
  static loadFromHtmlBuffer(
    buffer: Uint8Array | string,
    options?: HtmlOptions
  ): Promise<{ result: ParsedWorkbook }>;
}

WorkbookExporter

All methods are static.

class WorkbookExporter {
  /**
   * Serialize the spreadsheet to an XLSX binary buffer.
   * Preserves styles, merges, formulas, and formatting.
   * @param spreadsheet - A Worksheet instance from @worksheet-js/core
   */
  static exportToBuffer(spreadsheet: Spreadsheet): Promise<Uint8Array>;

  /**
   * Serialize a single sheet to a CSV string.
   * @param spreadsheet - A Worksheet instance from @worksheet-js/core
   * @param sheetIndex  - Zero-based sheet index. Defaults to the active sheet.
   */
  static exportToCsv(spreadsheet: Spreadsheet, sheetIndex?: number): string;

  /**
   * Trigger a browser Save As download dialog.
   * @param spreadsheet - A Worksheet instance from @worksheet-js/core
   * @param format      - 'xlsx' or 'csv'
   * @param filename    - Output filename including extension
   */
  static download(
    spreadsheet: Spreadsheet,
    format: 'xlsx' | 'csv',
    filename?: string
  ): Promise<void>;
}

Parsed Data Shape

interface ParsedWorkbook {
  workbook: {
    sheets: ParsedSheet[];
    definedNames?: DefinedName[];
    sharedStrings?: string[];
  };
}

interface ParsedSheet {
  name: string;
  cells: ParsedCell[][]; // Indexed [row][col], zero-based
  merges: MergeRange[];
  conditionalFormats: ConditionalFormat[];
  hyperlinks: Hyperlink[];
  dataValidations: DataValidation[];
  frozenRows?: number;
  frozenCols?: number;
}

interface ParsedCell {
  value: string | number | boolean | null;
  formula?: string; // Raw formula string (e.g. '=SUM(A1:A10)')
  style?: Partial<CellStyle>;
  type?: 'string' | 'number' | 'boolean' | 'date' | 'error';
}

Style Extraction

@worksheet-js/excel extracts richer styling metadata than most parsers:

| Style Property | Supported | | :----------------------------------------- | :-------: | | Font family, size, bold, italic, underline | ✅ | | Font color (theme + ARGB) | ✅ | | Cell background fill (solid + pattern) | ✅ | | Per-side border style and color | ✅ | | Horizontal and vertical alignment | ✅ | | Text wrap and indent level | ✅ | | Number format (built-in + custom) | ✅ | | Currency, percentage, date, accounting | ✅ | | Right-to-left text direction | ✅ | | Merged cell ranges | ✅ | | Conditional formatting rules | ✅ | | Hyperlinks | ✅ | | Data validation rules | ✅ |

License

Copyright © 2024-present Worksheet Systems. All rights reserved.

This software is proprietary. Usage is subject to the terms of the End-User License Agreement (EULA).

For licensing and technical support: [email protected]