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, options?)

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

| Parameter | Type | Description | | --------- | --------------------------- | ------------------------------ | | buffer | ArrayBuffer \| Uint8Array | The XLSX file contents | | options | TableParseOptions | Optional parsing configuration |

Options:

| Option | Type | Default | Description | | --------- | --------- | ------- | ------------------------------------------------- | | dateUTC | boolean | false | Interpret dates as UTC instead of local wall time |

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 | | detectDates | boolean | true | Convert ISO date strings to Date objects | | dateUTC | boolean | false | Interpret dates without an explicit timezone offset as UTC |

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

Helper Functions

excelDateToJS(excelDate, dateUTC?)

Converts Excel serial date number to JavaScript Date.

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

excelDateToJS(45678); // → local Date object for 2025-01-21
excelDateToJS(45678, true); // → UTC Date object for 2025-01-21

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 serialized with { dateUTC: true }:

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

Date Handling

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

Excel date values do not contain timezone information. By default, XLSX dates are created in the runtime's local timezone so their calendar date and time match Excel in browser applications. The same applies to CSV date values without an explicit timezone offset: 2025-01-15 becomes local midnight of January 15th, so it displays unchanged in the browser. Pass { dateUTC: true } (or true as the second argument to excelDateToJS) for UTC dates instead. CSV values with an explicit offset (2025-01-15T10:30:00Z, ...+05:30) always keep their own timezone.

| Function | Date Output | | ---------------------- | --------------------------------------------------------- | | parseWorkbook | Raw number + format field for detection | | parseWorkbookAsTable | JavaScript Date object (local by default, UTC optional) | | parseCsv | JavaScript Date object (local by default, UTC optional) |

CSV date detection can be turned off entirely with { detectDates: false }, which keeps date-like values as plain strings.

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 |

Changelog

0.2.0

Breaking behavior changes — dates are now local by default:

• parseWorkbookAsTable and excelDateToJS now create dates in the runtime's local timezone instead of UTC, so the displayed date and time match Excel in browser applications. Pass { dateUTC: true } (or true as the second argument to excelDateToJS) to restore the previous UTC behavior.
• parseCsv now also creates local dates for values without an explicit timezone offset. Previously date-only values (2025-01-15) were parsed as UTC midnight while datetime values without an offset were parsed as local time; both now consistently follow the dateUTC option (local by default). Values with an explicit offset (Z, +05:30) keep their own timezone, as before.

New options:

• parseWorkbookAsTable(buffer, { dateUTC }) — opt into UTC dates
• parseCsv(input, { dateUTC }) — opt into UTC dates
• parseCsv(input, { detectDates: false }) — disable date detection, keep date-like values as plain strings
• parseCsv now rejects date strings with out-of-range components (2024-13-01, 2024-02-31) instead of relying on engine parsing quirks; they stay strings

0.1.0

Initial release: XLSX parsing (parseWorkbook, parseWorkbookAsTable), CSV parsing (parseCsv), style extraction, date format detection.

License

MIT