ExcelTS

Modern TypeScript Excel Workbook Manager - Read, manipulate and write spreadsheet data and styles to XLSX and JSON.

About This Project

ExcelTS is a zero-dependency TypeScript toolkit for spreadsheets and documents:

🚀 Zero Runtime Dependencies — Pure TypeScript, no external packages
📦 Five Modules — Excel (XLSX/JSON), PDF (standalone engine + Excel bridge), CSV (RFC 4180), Archive (ZIP/TAR), Stream (cross-platform)
✅ Cross-Platform — Node.js 22+, Bun, Chrome 89+, Firefox 102+, Safari 14.1+
✅ ESM First — Native ES Modules with CommonJS compatibility and full tree-shaking

Translations

中文文档

Installation

npm install @cj-tech-master/excelts

Quick Start

Creating a Workbook

import { Workbook } from "@cj-tech-master/excelts";

const workbook = new Workbook();
const sheet = workbook.addWorksheet("My Sheet");

// Add data
sheet.addRow(["Name", "Age", "Email"]);
sheet.addRow(["John Doe", 30, "john@example.com"]);
sheet.addRow(["Jane Smith", 25, "jane@example.com"]);

// Save to file
// Node.js only: write to a file path
await workbook.xlsx.writeFile("output.xlsx");

// Browser: use `writeBuffer()` and save as a Blob (see the Browser Support section)

Reading a Workbook

import { Workbook } from "@cj-tech-master/excelts";

const workbook = new Workbook();
// Node.js only: read from a file path
await workbook.xlsx.readFile("input.xlsx");

// Browser: use `xlsx.load(arrayBuffer)` (see the Browser Support section)

const worksheet = workbook.getWorksheet(1);
worksheet.eachRow((row, rowNumber) => {
  console.log("Row " + rowNumber + " = " + JSON.stringify(row.values));
});

Styling Cells

// Set cell value and style
const cell = worksheet.getCell("A1");
cell.value = "Hello";
cell.font = {
  name: "Arial",
  size: 16,
  bold: true,
  color: { argb: "FFFF0000" }
};
cell.fill = {
  type: "pattern",
  pattern: "solid",
  fgColor: { argb: "FFFFFF00" }
};

Features

Excel Operations
- Create, read, and modify XLSX files
- Multiple worksheet support
- Cell styling (fonts, colors, borders, fills)
- Cell merging and formatting
- Row and column properties
- Freeze panes and split views
Data Handling
- Rich text support
- Formulas and calculated values
- Data validation
- Conditional formatting
- Images and charts
- Hyperlinks
- Pivot tables
PDF Export
- Full-featured, zero-dependency PDF engine (standalone or with Excel)
- Full cell styling (fonts, colors, borders, fills, alignment)
- Automatic pagination with repeat header rows
- TrueType font embedding for Unicode/CJK text
- JPEG and PNG image embedding with transparency
- Password protection and encryption
- Per-worksheet page setup (size, orientation, margins)
- Tree-shakeable (not imported = not bundled)
Advanced Features
- Streaming for large files
- CSV import/export
- Tables with auto-filters
- Page setup and printing options
- Data protection
- Comments and notes

Subpath Exports

ExcelTS provides focused subpath exports for standalone module usage:

// Main entry - Excel core (Workbook, Worksheet, Cell, etc.)
import { Workbook, WorkbookWriter } from "@cj-tech-master/excelts";

// ZIP/TAR archive utilities
import { zip, unzip, ZipArchive, compress } from "@cj-tech-master/excelts/zip";

// CSV parsing, formatting, and streaming
import { parseCsv, formatCsv, CsvParserStream } from "@cj-tech-master/excelts/csv";

// Cross-platform stream primitives
import { Readable, pipeline, createTransform } from "@cj-tech-master/excelts/stream";

Each subpath supports browser, import (ESM), and require (CJS) conditions. See the module READMEs for details:

PDF Module - Full-featured zero-dependency PDF engine with encryption and font embedding
CSV Module - RFC 4180 parser/formatter, streaming, data generation
Archive Module - ZIP/TAR create/read/edit, compression, encryption
Stream Module - Cross-platform Readable/Writable/Transform/Duplex

PDF Export

Export any workbook to PDF with zero external dependencies:

import { Workbook, excelToPdf } from "@cj-tech-master/excelts";

const workbook = new Workbook();
const sheet = workbook.addWorksheet("Report");
sheet.columns = [
  { header: "Product", key: "product", width: 20 },
  { header: "Revenue", key: "revenue", width: 15 }
];
sheet.addRow({ product: "Widget", revenue: 1000 });
sheet.getColumn("revenue").numFmt = "$#,##0.00";

// One-line export
const pdf = excelToPdf(workbook, {
  showGridLines: true,
  showPageNumbers: true,
  title: "Sales Report"
});

// Node.js: write to file
import { writeFileSync } from "fs";
writeFileSync("report.pdf", pdf);

// Browser: download
const blob = new Blob([pdf], { type: "application/pdf" });
const url = URL.createObjectURL(blob);
window.open(url);

Convert Existing XLSX to PDF

const workbook = new Workbook();
await workbook.xlsx.readFile("input.xlsx");
const pdf = excelToPdf(workbook);

Encryption

const pdf = excelToPdf(workbook, {
  encryption: {
    ownerPassword: "admin",
    userPassword: "reader",
    permissions: { print: true, copy: false }
  }
});

Unicode / CJK

import { readFileSync } from "fs";

const pdf = excelToPdf(workbook, {
  font: readFileSync("NotoSansSC-Regular.ttf") // TrueType font for CJK text
});

Standalone PDF (No Excel)

Generate PDFs from plain data — no workbook, no Map objects, no boilerplate:

import { pdf } from "@cj-tech-master/excelts/pdf";

// Simplest — pass a 2D array
const bytes = pdf([
  ["Product", "Revenue"],
  ["Widget", 1000],
  ["Gadget", 2500]
]);

// With column widths and styled cells
const bytes = pdf(
  {
    name: "Report",
    columns: [
      { width: 25, header: "Product" },
      { width: 15, header: "Revenue" }
    ],
    data: [
      ["Widget", 1000],
      ["Gadget", 2500]
    ]
  },
  { showGridLines: true }
);

For the full API reference and all options, see the PDF Module documentation.

Archive Utilities (ZIP/TAR)

ExcelTS includes internal ZIP/TAR utilities used by the XLSX pipeline. If you use the archive APIs directly, ZIP string encoding can be customized via ZipStringEncoding:

Default: "utf-8"
Legacy: "cp437"
Custom: provide a codec with encode/decode plus optional flags

When a non-UTF-8 encoding is used, Unicode extra fields can be emitted for better cross-tool compatibility.

Editing an existing ZIP (ZipEditor)

ExcelTS also includes a ZIP editor that can apply filesystem-like edits to an existing archive and then output a new ZIP.

Supports set(), delete(), rename(), deleteDirectory(), setComment()
Unchanged entries are passed through efficiently when possible

import { editZip } from "@cj-tech-master/excelts";

const editor = await editZip(existingZipBytes, {
  reproducible: true,

  // Passthrough behavior for unchanged entries:
  // - "strict" (default): raw passthrough must be available or it throws
  // - "best-effort": if raw passthrough is unavailable, fall back to extract+re-add
  preserve: "best-effort",
  onWarning: w => console.warn(w.code, w.entry, w.message)
});

editor.delete("old.txt");
editor.rename("a.txt", "renamed.txt");
editor.set("new.txt", "hello");

const out = await editor.bytes();

Streaming API

For processing large Excel files without loading them entirely into memory, ExcelTS provides streaming reader and writer APIs.

Node.js: WorkbookReader supports reading from a file path, and WorkbookWriter supports writing to a filename.
Browsers: use Uint8Array / ArrayBuffer / Web ReadableStream<Uint8Array> for reading, and Web WritableStream<Uint8Array> for writing.
Note: ExcelTS does not re-export the internal stream utility surface (e.g. Readable, Writable). Prefer standard Web Streams (browser/Node 22+) or Node.js streams.

Streaming Reader

Read large XLSX files with minimal memory usage:

import { WorkbookReader } from "@cj-tech-master/excelts";

// Node.js: read from file path
const reader = new WorkbookReader("large-file.xlsx", {
  worksheets: "emit", // emit worksheet events
  sharedStrings: "cache", // cache shared strings for cell values
  hyperlinks: "ignore", // ignore hyperlinks
  styles: "ignore" // ignore styles for faster parsing
});

for await (const worksheet of reader) {
  console.log(`Reading: ${worksheet.name}`);
  for await (const row of worksheet) {
    console.log(row.values);
  }
}

Streaming Writer

Write large XLSX files row by row:

import { WorkbookWriter } from "@cj-tech-master/excelts";

// Node.js: write to filename
const workbook = new WorkbookWriter({
  filename: "output.xlsx",
  useSharedStrings: true,
  useStyles: true
});

const sheet = workbook.addWorksheet("Data");

// Write rows one at a time
for (let i = 0; i < 1000000; i++) {
  sheet.addRow([`Row ${i}`, i, new Date()]).commit();
}

// Commit worksheet and finalize
sheet.commit();
await workbook.commit();

Web Streams (Node.js 22+ and Browsers)

WorkbookWriter can write to a Web WritableStream<Uint8Array>, and WorkbookReader can read from a Web ReadableStream<Uint8Array>.

This does not require importing any extra stream utility surface from ExcelTS; it uses the standard Web Streams API.

Full runnable example: src/modules/excel/examples/web-streams-reader-writer.ts

Run locally (Node.js 22+):

npx tsx src/modules/excel/ex

Excelts

Install / Use

README