Technical overview

The packages

All four packages install from npm with a free evaluation license. Commercial products need a commercial license.

The engine does the work: it loads, calculates and saves workbooks. Agent tools and the editor use the engine, which npm installs alongside them, and the viewer displays workbooks in your product.

• Engine@grid-is/spreadsheet-engineHeadless. Loads workbooks, calculates, reads and writes cells, and saves XLSX.
• Agent tools@grid-is/agent-toolsAn MCP server and SDK tools that let AI agents work on workbooks.
• Editor@grid-is/spreadsheet-editorA React component (React 18 or later) that adds spreadsheet editing to your product.
• Viewer@grid-is/spreadsheet-viewerA lightweight React component (React 18 or later) that displays workbooks on a canvas.

Several of the engine’s building blocks are open source. JSFKit, built by GRID’s engineers, has the TypeScript packages the engine uses to read XLSX files, work with Excel formulas and format numbers, along with the JSF spec.

Where the engine runs

The engine is written in TypeScript and ships with its types. It runs wherever your code runs, on a device or on a server.

On device

Calculations can run entirely on the user’s device, with no round trip to a server. Excel files load straight into the engine, and every change recalculates on the device as the user works.

The viewer and editor, both React components, can display and edit the same spreadsheet on the user’s device, for example in a browser.

On a server

The engine also runs on Node.js and compatible runtimes for server-side work, like a pricing or quoting API, batch processing of uploaded workbooks, scheduled reports, or an AI agent working through the GRID agent tools. It loads Excel workbooks into a model that recalculates with any inputs you give it, and saves the result back as .xlsx. It runs on whatever infrastructure you have, on premises or in the cloud.

File types

The engine opens .xlsx and .xlsm files, and saves workbooks as .xlsx. Google Sheets workbooks load as Excel exports, and the engine’s Google Sheets mode calculates them the way Sheets does.

It also reads and writes JSF, GRID’s open JSON workbook format. Because it’s plain JSON, it makes the engine much easier to build into web applications, and it’s handy for keeping workbooks in a database or sending them through an API.

Macros and VBA are removed when a workbook loads, so they never run and aren’t in the saved file. For what carries through a round trip, feature by feature, see Features.

How the engine calculates

A workbook is a graph. Every cell is a node, and every formula connects a cell to the cells it reads. The engine keeps that graph up to date and uses it to do as little work as possible.

1. 1Map the dependency graphWhen a workbook loads, the engine builds a graph of which cells depend on which.
2. 2Mark what’s affectedWhen a value changes, it marks every cell downstream of it as out of date, and nothing else.
3. 3Recalculate only what’s neededIt recalculates only the marked cells, each one once and in dependency order, so the work scales with the change, not the workbook.

The hard parts of real spreadsheets are handled too:

• Excel’s exact number handling: comparisons, rounding, tie-breaking, zero cancellation, overflow and number formatting
• Edits that keep formulas right: inserting, deleting or moving rows, columns, cells and sheets rewrites every formula, defined name, table and 3-D reference that depends on them
• Pivot tables that refresh to Excel’s layout, with Show Values As, GETPIVOTDATA, GROUPBY and PIVOTBY
• Dynamic arrays and spills, alongside legacy array formulas and the older implicit-intersection rules
• LAMBDA and LET, including recursion, scoping, passing functions as values, and lambdas in MAP, BYROW and REDUCE
• Dependencies only known as a formula calculates: OFFSET and INDIRECT, circular references with iterative calculation, and IF and SWITCH branches worked out only when taken
• What-if analysis: data tables and Goal Seek

The engine has a compatibility mode for Excel and one for Google Sheets, and supports over 500 of their functions. See the full lists of supported functions and operators.

Code examples

Engine

Install the engine from npm.

This code opens the pricing spreadsheet from the example above, sets the seats to 100, reads back the recalculated quote, works out the price per seat with a formula of its own and saves the result as a new file.

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

// Wait for the WebAssembly formula parser
await Model.preconditions;

const model = await Model.fromXLSXFile('pricing.xlsx');

// Set the seats: D2, D6 and the quote in D9 recalculate
model.write('B2', 100);

const quote = model.readValue('=D9'); // 5400

// Work out a formula that isn't in the sheet
const perSeat = model.runFormula('=D9/B2'); // 54

const workbook = model.getWorkbook('pricing.xlsx');
await workbook.toXLSXFile('pricing-100-seats.xlsx');

The API reference covers every class and method, including loading files in the browser.

Agent tools

Here’s a simple pricing agent workflow, using GRID’s tools to calculate a quote from a pricing spreadsheet:

loadWorkbook({
  "path": "pricing.xlsx"
})

describeStructure({})

readCalculatedValues({
  "apply": [{
    "cell": "B2",
    "value": 100
  }],
  "read": ["D9"]
})

Connect your agent

There are two ways to give your agent GRID’s tools. The quickest is to start the MCP server, which works with Claude, Cursor and any other MCP-capable agent:

The other is to build the tools into your own agent. Each tool is a plain object with a name, a description, an input schema and a function that runs it. Turn the schemas into JSON Schema for your agent SDK, and run a tool when the model calls it:

import { z } from 'zod';
import { createGridTools } from '@grid-is/agent-tools';

const tools = createGridTools();

// Tool definitions for any agent SDK
const definitions = tools.map((tool) => ({
  name: tool.name,
  description: tool.description,
  parameters: z.toJSONSchema(z.object(tool.inputSchema)),
}));

// When the model calls a tool, run it and send back the text
const tool = tools.find((t) => t.name === call.name);
const { text } = await tool.run(call.args);

Learn more about what agents can do with GRID’s agent tools.

Next steps

• Get started
• Engine docs
• Agent tools docs
• Features
• Security