Getting started with the Spreadsheet Engine

In this guide we’ll install GRID’s spreadsheet engine, load an Excel file, run a formula on the data it contains, and print the answer. This guide assumes you’re using Node.js and npm on a Unix-like system. We used Node.js v22.11.0 and npm v10.9.0 when writing this tutorial.

Create a new directory and initialise an npm project inside it:

mkdir spreadsheet-engine-quickstart
cd spreadsheet-engine-quickstart
npm init --init-type module -y

Add the spreadsheet engine as a dependency:

npm install @grid-is/spreadsheet-engine

The package is published publicly on npm, so any of these work too:

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

Grab a copy of our example spreadsheet. For this demo we’ll use a simple workbook that tracks monthly household expenses, categorises our spending, and lists a budget and actual spend per category. Save a local copy of budget.xlsx alongside the project you just created.
Now to the meat of it. Create an index.js file in your project directory with this content:
```
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 });
```
What does the code do?
Walking through it line by line:
import { Model } from "@grid-is/spreadsheet-engine";
The Model class is the engine’s main interface to a collection of one or more workbooks. Your interactions with spreadsheets all happen through a Model instance.
await Model.preconditions;
This waits for the engine’s WebAssembly module to finish initialising. You only need to do this once per process before you call any other Model method.
const model = await Model.fromXLSXFile("budget.xlsx");
Next we read a local .xlsx file from disk and load it as a model. Note that Model.fromXLSXFile is Node-only. In the browser you’d fetch the file and pass an ArrayBuffer to Model.fromXLSX instead.
const totalSpent = model.runFormula("=SUM(D:D)"); console.info({ totalSpent });
The final step is to evaluate an Excel formula against the workbook. =SUM(D:D) sums every numeric value in column D (in our example, the amount spent per category) and we print the total to the terminal.
The engine’s formula evaluator is shipped as a WebAssembly module, so Node needs the --experimental-wasm-modules flag to load it:
Terminal window
```
node --experimental-wasm-modules index.js
```
If you’re using a version of Node newer than v24.5.0 or v22.19.0, you no longer need to include the --experimental-wasm-modules flag. Node works without it.

You should see the licence banner followed by the total:
```
{ totalSpent: 6945 }
```

Where to next

See our Tips page for more examples of loading workbooks in the browser, starting from a blank model, reading and writing cells, and exporting .xlsx files.

The API reference covers every class, method, and type the engine exposes. A few useful starting points:

Model: load workbooks, run formulas, read and write cells
Workbook: work with a single workbook within a model, including saving it back out as .xlsx
WorkSheet: interact with an individual sheet
Cell: the shape of a cell as returned by readCell and readCells