xlsx-parser

A lightweight TypeScript library for parsing XLSX and CSV files. Extracts cell values with style support and minimal dependencies (~5KB gzipped).

Installation

bun add xlsx-reader-lite
# or
npm install xlsx-reader-lite

Usage

import { parseWorkbook, parseWorkbookAsTable, parseCsv } from 'xlsx-reader-lite';
import { readFileSync } from 'fs';

// XLSX - Cell format with styles
const buffer = readFileSync('spreadsheet.xlsx');
const workbook = parseWorkbook(buffer);

// XLSX - Table format (2D matrix with date conversion)
const tables = parseWorkbookAsTable(buffer);
cat;
// CSV - Auto-detects separator, converts types
const csvData = readFileSync('data.csv', 'utf-8');
const sheet = parseCsv(csvData);

API

XLSX Parsing

parseWorkbook(buffer)

Parses an XLSX file and returns cells with style information.

| Parameter | Type | Description | | --------- | --------------------------- | ---------------------- | | buffer | ArrayBuffer \| Uint8Array | The XLSX file contents |

Returns: Workbook (array of sheets with cells and styles)

parseWorkbookAsTable(buffer)

Parses an XLSX file and returns a 2D matrix format with automatic date conversion.

| Parameter | Type | Description | | --------- | --------------------------- | ---------------------- | | buffer | ArrayBuffer \| Uint8Array | The XLSX file contents |

Returns: TableWorkbook (array of sheets with row-major 2D arrays)

CSV Parsing

parseCsv(input, options?)

Parses CSV data with automatic separator detection and type conversion.

| Parameter | Type | Description | | --------- | ----------------- | -------------------------------------- | | input | string \| Blob | CSV content (returns Promise for Blob) | | options | CsvParseOptions | Optional parsing configuration |

Options:

| Option | Type | Default | Description | | ----------------- | -------- | ----------- | ------------------------------------------------------- | | columnSeparator | string | auto-detect | Column separator (detects: tab, comma, semicolon, pipe) | | rowSeparator | string | \n | Row separator (handles \r\n automatically) | | name | string | "Sheet1" | Sheet name for output |

Returns: TableSheet (or Promise<TableSheet> for Blob input)

Helper Functions

excelDateToJS(excelDate)

Converts Excel serial date number to JavaScript Date.

import { excelDateToJS } from 'xlsx-reader-lite';

excelDateToJS(45678); // → Date object for 2025-01-15

parseCellRef(ref)

Parses cell reference string to column/row indices (0-indexed).

import { parseCellRef } from 'xlsx-reader-lite';

parseCellRef('A1'); // → { col: 0, row: 0 }
parseCellRef('B2'); // → { col: 1, row: 1 }
parseCellRef('AA1'); // → { col: 26, row: 0 }

Output Formats

Cell Format (parseWorkbook)

Returns an array of sheets with cells, styles, and format info:

type Workbook = Sheet[];

interface Sheet {
  name: string;
  data: Cell[];
  styles?: Record<number, CellStyle>; // Style definitions used by cells
}

interface Cell {
  id: string; // Cell reference ("A1", "B2", etc.)
  value: string | number | null;
  format?: string; // Number format ("yyyy-mm-dd", etc.)
  style?: number; // Index into Sheet.styles
}

interface CellStyle {
  fontWeight?: 'bold';
  fontStyle?: 'italic';
  textDecoration?: string; // "underline", "line-through"
  fontSize?: string; // "11pt"
  fontFamily?: string; // "Calibri"
  color?: string; // "#FF0000"
  backgroundColor?: string; // "#FFFF00"
  borderTop?: string; // "1px solid #000000"
  borderRight?: string;
  borderBottom?: string;
  borderLeft?: string;
  textAlign?: 'left' | 'center' | 'right' | 'justify';
  verticalAlign?: 'top' | 'middle' | 'bottom';
  whiteSpace?: 'normal' | 'nowrap' | 'pre-wrap';
}

Example output:

[
  {
    "name": "Sheet1",
    "data": [
      { "id": "A1", "value": "Name", "style": 0 },
      { "id": "B1", "value": "Date", "style": 0 },
      { "id": "A2", "value": "Alice" },
      { "id": "B2", "value": 45678, "format": "yyyy-mm-dd" }
    ],
    "styles": {
      "0": { "fontWeight": "bold", "backgroundColor": "#FFFF00" }
    }
  }
]

Table Format (parseWorkbookAsTable, parseCsv)

Returns sheets with 2D matrix data. Dates are automatically converted to JavaScript Date objects.

type TableWorkbook = TableSheet[];

interface TableSheet {
  name: string;
  data: TableRow[];
}

type TableRow = (string | number | Date | null)[];

Example output:

[
  {
    "name": "Sheet1",
    "data": [
      ["Name", "Date"],
      ["Alice", "2025-01-15T00:00:00.000Z"]
    ]
  }
]

Date Handling

Excel stores dates as numbers (days since 1900-01-01).

| Function | Date Output | | ---------------------- | ----------------------------------------- | | parseWorkbook | Raw number + format field for detection | | parseWorkbookAsTable | JavaScript Date object (auto-converted) | | parseCsv | JavaScript Date object (ISO 8601 only) |

Detected XLSX date formats:

• Built-in: mm-dd-yy, d-mmm-yy, m/d/yy h:mm, etc.
• Custom: Any format containing y, m, d, h, s patterns

Detected CSV date formats:

• ISO 8601: 2025-01-15, 2025-01-15T10:30:00, 2025-01-15T10:30:00Z

Cell Types

XLSX

| Excel Type | parseWorkbook | parseWorkbookAsTable | | ---------- | ------------------- | ---------------------- | | String | string | string | | Number | number | number | | Boolean | number (0 or 1) | number (0 or 1) | | Date | number + format | Date | | Empty | null | null | | Formula | Result value | Result value |

CSV

| Content Type | Output | | ------------ | -------- | | Number | number | | ISO Date | Date | | Empty | null | | Other | string |

Browser Usage

For CDN/browser usage, use the bundled version:

<script type="module">
  import { parseWorkbook, parseWorkbookAsTable, parseCsv } from './xlsx-parser.bundle.js';

  // XLSX
  const response = await fetch('spreadsheet.xlsx');
  const buffer = await response.arrayBuffer();
  const workbook = parseWorkbookAsTable(buffer);

  // CSV
  const csvResponse = await fetch('data.csv');
  const csvText = await csvResponse.text();
  const sheet = parseCsv(csvText);

  console.log(workbook, sheet);
</script>

Limitations

• Read-only: No write/export support
• Formulas: Only results, not formulas themselves
• No streaming: Entire file loaded into memory

Bundle Size

| Build | Size | | ------------------ | ------ | | Library (ESM) | ~10 KB | | Bundled (all deps) | ~12 KB | | Bundled + gzipped | ~5 KB |

License

MIT