@grid-is/spreadsheet-engine

Evaluation version of GRID's high-performance spreadsheet engine, Apiary.

It is one of three complementary packages for working with spreadsheets:

• @grid-is/spreadsheet-engine (this package): the headless engine that loads workbooks, evaluates formulas, and reads and writes cells. No React required.
• @grid-is/spreadsheet-viewer: a React component that renders an engine model as a read-only spreadsheet UI.
• @grid-is/spreadsheet-editor: a React component that renders an engine model as an editable spreadsheet UI.

Installation

Add our spreadsheet engine as a project dependency with npm:

npm install @grid-is/spreadsheet-engine

You can also use another package manager if you'd prefer:

pnpm add @grid-is/spreadsheet-engine
# or
deno add npm:@grid-is/spreadsheet-engine
# or
bun add @grid-is/spreadsheet-engine
# or
yarn add @grid-is/spreadsheet-engine

Using with an AI coding agent

If you are working with a coding agent (Claude Code, Cursor, Copilot, and the like), install GRID's skill so the agent gets the full, up-to-date guide for all three packages:

npx skills add GRID-is/skills

Whether or not the skill is installed, the rules below are the things that trip agents up first.

Golden rules

1. Await Model.preconditions once before using the engine. The formula parser loads asynchronously and most Model entry points throw if it has not resolved.

   import { Model } from "@grid-is/spreadsheet-engine";
   await Model.preconditions;

2. Value writes recalculate automatically; formula writes do not. model.write("B2", 42) recalculates dependents, but writing a formula via wb.editCell("B5", { f: "=SUM(A1:A4)" }) leaves the cell unresolved until you recalculate:

   import { ALL_FORMULA_CELLS } from "@grid-is/spreadsheet-engine";
   wb.editCell("B5", { f: "=SUM(A1:A4)" });
   model.recalculate(ALL_FORMULA_CELLS);

3. Read expressions start with =; write references do not. Use model.readValue("=B2") but model.write("B2", 42). The read methods accept any formula expression, not just a reference.

4. Model.fromXLSXFile and toXLSXFile are Node-only. In the browser use Model.fromXLSX(arrayBuffer, filename) and wb.toXLSX("arraybuffer").

5. This package is ESM-only. Use import, not require. The dist bundle is self-contained, with no runtime dependencies to install alongside it.

6. Sheet references: an unprefixed ref (A1, D:F) hits the first sheet. Use Sheet2!A1, and single-quote names that contain spaces, e.g. 'My Sheet'!A1.

Authoritative API

The bundled type definitions are the source of truth and ship with the package. Every public method carries JSDoc, often with examples. When in doubt, read or grep them rather than guessing a method name. If it is not in the .d.ts, it does not exist.

grep -n "goalSeek\|insertRows\|describeWorkbook" node_modules/@grid-is/spreadsheet-engine/dist/index.d.ts

This package also ships an AGENTS.md in its root, which points agent tools that look for that file by name back to this guide.

Getting started

The main interface in GRID's spreadsheet engine is the Model class. It represents a collection of workbooks (one or more) and provides methods to read and write cell values, run formulas, and more.

You can use Model to load a local spreadsheet and run a formula on it like this:

import { Model } from "@grid-is/spreadsheet-engine";

await Model.preconditions;
const model = await Model.fromXLSXFile("budget.xlsx");
const totalSpent = model.runFormula("=SUM(D:D)");
console.info({ totalSpent });

The Model.fromXLSXFile method we use above is Node-only. To load a spreadsheet in a browser environment, use Model.fromXLSX with an ArrayBuffer:

const res = await fetch("/budget.xlsx");
const model = await Model.fromXLSX(await res.arrayBuffer(), "budget.xlsx");

You can also start with a blank workbook by creating an empty model (no XLSX file required):

const model = Model.empty("workbook.xlsx");

As well as running formulas with Model.runFormula, you can read and write cell values:

// Get the value in a cell (string, number, boolean, null, or error)
const revenue = model.readValue("=B2");
// Get the full cell object
const revenue = model.readCell("=B2");
// Get a 2D array of cell objects
const table = model.readCells("=A1:C10");

// Write a value to a single cell
model.write("B2", 42);
// Write multiple cells in one recalculation pass
model.writeMultiple([
  ["B2", 42],
  ["B3", "Total"],
  ["B4", true],
]);
// Write a formula to a cell (requires a workbook's dependency graph to be rebuilt)
const wb = model.getWorkbook("budget.xlsx");
wb.editCell("B5", { f: "=SUM(E4:E17)" });

To save a workbook as a .xlsx file in Node:

await model.getWorkbook("budget.xlsx").toXLSXFile("budget-final-draft-v2-FINAL.xlsx");

Or to download it in a browser:

const buffer = await model.getWorkbook("budget.xlsx").toXLSX("arraybuffer");
const blob = new Blob([buffer], {
  type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
});
const url = URL.createObjectURL(blob);
const a = Object.assign(document.createElement("a"), { href: url, download: "budget.xlsx" });
a.click();
URL.revokeObjectURL(url);

Referencing specific sheets

By default, when you refer to cells without a sheet name (e.g. A1, A1:B4, D:F), the engine will look at the first sheet in the workbook. To reference a cell in a specific sheet, include the sheet name followed by an exclamation mark (e.g. Sheet2!A1, Sheet2!A1:B4, Sheet2!D:F). If a sheet name includes a space you must wrap the name in single quotes (e.g. 'My Sheet'!A1, 'My Sheet'!A1:B4, 'My Sheet'!D:F).

Resources

Find out more about GRID's spreadsheet engine capabilities in the API docs. Some starting points:

• Model
• Workbook
• WorkSheet
• Cell

Conditions of use

This package is free to install and use under the following conditions. By installing it, you agree to the GRID Evaluation Licence. Permitted use:

• Internal evaluation to determine whether GRID fits your needs
• Internal prototypes and proofs of concept in non-production environments

Not permitted:

• Commercial use of any kind --- including any product, internal service, or workflow that generates revenue or cost savings, directly or indirectly
• Use in production environments
• Reverse engineering or attempting to access the source code
• Creating derivative works or modified versions
• Redistributing or sublicensing the package

If you want to get yourself set up commercially, visit https://grid.is/license.

Telemetry

While you evaluate our spreadsheet engine, we collect anonymous telemetry to understand usage patterns. Once you license our package, all telemetry is removed.

On load, the package sends the following information to PostHog:

• Package name and version
• Environment (prod or dev)
• Runtime (Node or browser)
• If running via Node: Node version and platform
• If running in the browser: user agent, language, timezone

No spreadsheet data is shared with PostHog or any other service.