Quick start

Install

npm install @byfungsi/nori

For the React renderer, also install compatible React peers:

npm install react@^19 react-dom@^19

Headless use does not require React. The package is ESM; use an ESM application or a compatible bundler. Repository development requires Node 22.12 or later. Native bindings are future work.

For editor appearance, see Styling and theming. Nori does not ship an editor stylesheet; the guide provides a complete application CSS starter.

Calculate and persist a workbook

This is a complete, typechecked example. Expected failures are Result values; this short program chooses to throw after checking them. An application should display or return these errors at its boundary.

import { createEmptySnapshot, createWorkbook } from "@byfungsi/nori";

export function makeWorkbook() {
  const created = createWorkbook(createEmptySnapshot());
  if (!created.ok) throw created.error;
  const workbook = created.value;
  const sheetId = workbook.getState().activeSheetId;
  const edited = workbook.dispatch({
    type: "batch",
    commands: [
      { type: "setCell", sheetId, address: "A1", cell: { value: 100 } },
      { type: "setCell", sheetId, address: "A2", cell: { value: 50 } },
      {
        type: "setCell",
        sheetId,
        address: "A3",
        cell: { value: null, formula: "SUM(A1:A2)" },
      },
    ],
  });
  if (!edited.ok) throw edited.error;
  return workbook;
}

const workbook = makeWorkbook();
const sheetId = workbook.getState().activeSheetId;
console.log(workbook.getCellValue(sheetId, "A3")); // 150
const json = JSON.stringify(workbook.exportSnapshot());
const restored = createWorkbook(JSON.parse(json));
if (!restored.ok) throw restored.error;

WorkbookSnapshot is immutable JSON-compatible document data. Workbook is a live runtime with commands, subscriptions, history and calculated values. Persist the snapshot, never the runtime object. Exported cell values may be old formula caches; read calculated results through getCellValue.

Choose an import

Import	Purpose
@byfungsi/nori	Convenient model constructors, XLSX parser and runtime
@byfungsi/nori/model	Canonical types, validation, addresses, ranges and Result helpers
@byfungsi/nori/core	Runtime, commands, selection and layout
@byfungsi/nori/csv	Text CSV to a single-sheet snapshot
@byfungsi/nori/xlsx	Byte-to-snapshot adapter
@byfungsi/nori/formula	AST parser, evaluator, registry and dependency graph
@byfungsi/nori/pivot	Semantic grouping and aggregation
@byfungsi/nori/react	React DOM components and hooks

Only /react imports React. Prefer /core when you do not need XLSX dependencies. Internal workspace names are implementation details and must not appear in consumer code.

Continue with React, XLSX import, or headless recipes.