Skip to content
Apiary

Getting started with Apiary

In this guide we’ll load an Excel file into GRID’s spreadsheet engine, run a formula on the data it contains, and output 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.

  1. Let’s start by creating a new directory and using it for a new npm-based project:

    Terminal window
    mkdir apiary-quickstart
    cd apiary-quickstart
    npm init -y
  2. Next, we’ll configure npm to download packages within the @grid-is scope from npmjs.com. This will give you access to GRID’s private spreadsheet engine package, Apiary. Create a .npmrc file:

    Terminal window
    cat << 'EOF' > .npmrc
    @grid-is:registry=https://registry.npmjs.org
    //registry.npmjs.org:_authToken=${NPM_TOKEN}
    EOF
  3. Now we can add the project’s dependency — the spreadsheet engine itself, known as Apiary:

    Terminal window
    npm add @grid-is/apiary
  4. Grab a copy of our example spreadsheet. For this demo, we’ll use a simple spreadsheet that tracks monthly household expenses. It categorises our spending, provides a budget for each category, and tracks actual spending. Save a local copy of budget.xlsx so we can use it in our project.

  5. Now to the meat of it. Let’s write some code that can open a spreadsheet and interact with it. Create an index.js file and copy this code in:

    import { Model } from '@grid-is/apiary';
    const model = await Model.fromXLSXFile("budget.xlsx");
    const totalSpent = model.runFormula("=SUM(D:D)");
    console.info({ totalSpent });
  6. Once you have the budget.xlsx file and the code in index.js, we can run it using Node:

    Terminal window
    node index.js

    After running that, you’ll see our monthly expenditure printed out in your terminal:

    { totalSpent: 6945 }