Index of every page on this site: llms.txt
All skills
Run it yourself

Specialized assistant for using ExcelJS to read, manipulate, and write spreadsheet data and styles to XLSX and JSON formats.

  • 1 file
  • 8.1 KB
  • Updated 9 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/corey-alix/dwp-hours/exceljs

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈33 tokens for metadata: the name and description. ≈2k when used: this file.

Description uses 1.7% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈134 characters, or 1.7%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

exceljs.skill.md

Introduction

ExcelJS is a JavaScript library for reading, manipulating, and writing spreadsheet data and styles to XLSX and JSON formats. It is reverse-engineered from Excel spreadsheet files.

Installation

npm install exceljs

Key Features

  • Read/write XLSX and JSON
  • Support for formulas, styles, images, merges
  • Conditional formatting, data validation
  • Tables, pivot tables (limited), cell comments
  • Streaming I/O for large files
  • Browser compatibility (document-based only)

Basic Usage

Creating Workbook

const workbook = new ExcelJS.Workbook();

Adding Worksheets

const sheet = workbook.addWorksheet("My Sheet", {
  properties: { tabColor: { argb: "FFC0000" } },
  views: [{ showGridLines: false }],
});

Writing Data

// Add row by object
worksheet.addRow({ id: 1, name: "John" });

// Add row by array
worksheet.addRow([2, "Jane", new Date()]);

// Set cell value
worksheet.getCell("A1").value = "Hello";

Styling

// Cell styling
worksheet.getCell("A1").numFmt = "0.00";
worksheet.getCell("A1").font = { name: "Arial", size: 12 };

// Column styling
worksheet.columns = [
  { header: "ID", key: "id", width: 10, style: { font: { bold: true } } },
];

Reading Files

// Read XLSX
await workbook.xlsx.readFile("file.xlsx");

// Read CSV
const worksheet = await workbook.csv.readFile("data.csv");

Advanced Usage

Formulas

// Simple formula
worksheet.getCell("A3").value = { formula: "A1+A2", result: 10 };

// Shared formula
worksheet.getCell("A2").value = {
  formula: "A1",
  result: 5,
  shareType: "shared",
  ref: "A2:B3",
};

// Array formula
worksheet.fillFormula("A2:B3", "A1", [1, 1, 1, 1], "array");

Images

// Add image to workbook
const imageId = workbook.addImage({ filename: "image.jpg", extension: "jpeg" });

// Add to worksheet
worksheet.addImage(imageId, "B2:D6");

Merges

worksheet.mergeCells("A1:B2");
worksheet.getCell("A1").value = "Merged";

Tables

ws.addTable({
  name: "Sales",
  ref: "A1",
  headerRow: true,
  totalsRow: true,
  columns: [{ name: "Date" }, { name: "Amount", totalsRowFunction: "sum" }],
  rows: [[new Date(), 100]],
});

Conditional Formatting

worksheet.addConditionalFormatting({
  ref: "A1:E7",
  rules: [
    {
      type: "expression",
      formulae: ["MOD(ROW()+COLUMN(),2)=0"],
      style: {
        fill: {
          type: "pattern",
          pattern: "solid",
          fgColor: { argb: "FFFF00" },
        },
      },
    },
  ],
});

API Overview

Main Classes

  • Workbook: Root object containing worksheets
  • Worksheet: Represents a worksheet with rows, columns
  • Row: Represents a row with cells
  • Cell: Represents a cell with value and style

Key Methods

  • workbook.addWorksheet(name, options)
  • worksheet.addRow(values, style)
  • worksheet.mergeCells(range)
  • workbook.xlsx.writeFile(filename)
  • workbook.xlsx.readFile(filename)
  • worksheet.getCell(address)
  • worksheet.addImage(imageId, location)

Examples

Create and Write Workbook

const workbook = new ExcelJS.Workbook();
const sheet = workbook.addWorksheet("Data");

sheet.columns = [
  { header: "Name", key: "name", width: 32 },
  { header: "DOB", key: "dob", width: 10 },
];

sheet.addRow({ name: "John", dob: new Date(1990, 0, 1) });
sheet.addRow({ name: "Jane", dob: new Date(1985, 5, 15) });

await workbook.xlsx.writeFile("output.xlsx");

Read and Process File

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

workbook.eachSheet((worksheet) => {
  worksheet.eachRow((row, rowNumber) => {
    console.log(`Row ${rowNumber}:`, row.values);
  });
});

Important Notes

  • Styles are shared by reference; modify with caution
  • Streaming I/O requires explicit commit() on rows
  • Browser support limited to document-based operations
  • Worksheet IDs may not be sequential after deletions
  • Use workbook.eachSheet() instead of forEach for iteration
  • Polyfills required for ES5 or older Node.js versions

Streaming Reader (Memory-Constrained Environments)

CRITICAL: workbook.xlsx.readFile() and workbook.xlsx.load(buffer) load the entire workbook into memory at once. For workbooks with many sheets (e.g., 68 employee tabs), this can easily exceed 200MB and cause OOM kills on memory-constrained servers (512MB).

Use WorkbookReader for Large Files

const reader = new ExcelJS.stream.xlsx.WorkbookReader(filePath, {
  worksheets: "emit", // stream worksheets one at a time
  sharedStrings: "cache", // cache shared strings for cell values
  styles: "cache", // cache styles so cell.style works
  hyperlinks: "cache", // cache hyperlinks
});

for await (const wsReader of reader) {
  const sheetName = (wsReader as any).name; // name not in type defs but exists at runtime

  for await (const row of wsReader) {
    row.eachCell({ includeEmpty: false }, (cell, colNumber) => {
      // Process cell...
    });
  }
}

Materialising Individual Sheets

If existing parse helpers require random cell access (ws.getCell(row, col)), materialise one sheet at a time into a temporary Worksheet, process it, then let it be garbage collected:

async function materialiseWorksheet(
  wsReader: ExcelJS.stream.xlsx.WorksheetReader,
): Promise<ExcelJS.Worksheet> {
  const tempWB = new ExcelJS.Workbook();
  const ws = tempWB.addWorksheet((wsReader as any).name || "Sheet");

  for await (const row of wsReader) {
    const newRow = ws.getRow(row.number);
    row.eachCell({ includeEmpty: false }, (cell, colNumber) => {
      const newCell = newRow.getCell(colNumber);
      newCell.value = cell.value;
      newCell.style = cell.style;
      if (cell.note) newCell.note = cell.note;
    });
    newRow.commit();
  }

  return ws;
}

Type Definition Gaps

  • WorksheetReader.name exists at runtime but is not in the type definitions — use (wsReader as any).name
  • WorkbookReader constructor options are typed as Partial<WorkbookStreamReaderOptions>

Key Differences from Standard Reader

Feature readFile() / load() WorkbookReader
Memory All sheets at once One sheet at a time
Cell access Random (getCell) Sequential (row iteration)
Styles/fills Always available Requires styles: "cache"
Sheet names worksheet.name (wsReader as any).name
Merged cells Tracked automatically May need manual handling

Cell Inspection Tooling

The project includes scripts/query-xlsx.mts for ad-hoc cell inspection during development and debugging. Run it via:

pnpm query:xlsx --file <path> --sheet <name> --cell <ref>

What It Reports

  • Value (raw): The underlying cell.value (number, string, rich text object, formula result)
  • Text: The display string via cell.text (always a plain string)
  • Type: ExcelJS cell type enum value
  • Formula: If present, the formula string
  • Fill: Pattern type, fgColor and bgColor — including theme index and tint when the color is theme-based rather than ARGB
  • Note/Comment: Rich text comment structure with author and text segments
  • Font: Name, size, bold, italic, color
  • Number Format / Alignment: If set on the cell

Theme Colors vs ARGB

Excel files frequently use theme-indexed colors instead of literal ARGB values. When inspecting a cell, you may see:

{ "fgColor": { "theme": 9 } }

instead of:

{ "fgColor": { "argb": "FFFFC000" } }

This means the color is resolved at render time from the workbook's theme palette. Code that matches colors by fgColor.argb alone will miss these cells. Use the query tool to diagnose such mismatches during import development.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at e4fbc1d. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Dormantupdated 9 months ago

README badge

README badge for corey-alix/dwp-hours/exceljs