Bilig is for backend and tool-integration developers who need to read calculated workbook values from Node without driving Excel or a browser grid.

Is bilig a complete Excel clone?

No. It focuses on programmatic workbook workflows: write inputs, recalculate formulas, read outputs, and persist state. The compatibility notes document Excel behavior that is not complete yet.

Can I use bilig from TypeScript?

Yes. Use @bilig/workpaper for a service-owned workbook model and @bilig/xlsx-formula-recalc only when an existing XLSX file remains the contract.

Use Bilig when code needs fresh formula readback from workbooks before an API, queue worker, CI job, or workflow trusts the result.

When should I try bilig instead of ExcelJS, SheetJS, or HyperFormula?

Try it when the job is not just file read/write or formula calculation. Bilig adds a WorkPaper object model, cell mutation, recalculation, output readback, JSON persistence, and agent/MCP tool boundaries.

bilig - WorkPaper Runtime for Node

Who needs this

Teams that keep business rules in workbook formulas.

Pricing, payout, approval, import, and forecast rules often start in cells. Bilig lets backend code run those cells directly instead of turning every rule into one-off service code.

first run Run the workbook model before you adopt it.

The evaluator writes one input, reads the formula output, saves the WorkPaper JSON, restores it, and checks the restored value. No account, no repo clone, no spreadsheet UI.

npm exec --yes --package @bilig/workpaper@latest -- \
  bilig-evaluate --door workpaper-service --json

WorkPaper npm create @bilig/workpaper@latest pricing-workpaper Generate a small service or tool starter wired to the same runtime. service Put a WorkPaper behind a Node route. Wire formula-backed state into an API, queue worker, CLI, or tool. tools bilig-evaluate --door agent-mcp --json Expose cell reads, writes, formula readback, and JSON export over MCP. rules Pick the right host rule file. Route Codex, Claude Code, Copilot, VS Code, Cursor, Kiro, Roo Code, Trae, Qodo IDE, Zed, OpenCode, Goose, Windsurf, Cline, Continue, and Gemini CLI. proof Choose the smallest tool-host proof. Compare WorkPaper service, MCP, AI SDK, OpenAI, LangGraph, Semantic Kernel, Mastra, ExcelJS, and XLSX paths. XLSX xlsx-recalc --read Summary!B7 Import, recalculate, and export files when XLSX is still the contract.

Use @bilig/workpaper for starters, evaluators, service code, and tool integrations. Use saved-file packages only when XLSX is the boundary.

Market gap

Not another spreadsheet UI. Not just a formula engine.

File libraries move workbook bytes. Formula engines calculate formulas. Hosted spreadsheets need networked app state. Bilig targets the missing runtime layer for backend teams that need workbook-shaped logic under test.

01 / model

Keep the business rule readable.

Represent inputs, formulas, and outputs as sheets instead of burying every rule in custom service code.

02 / run

Let the service change the inputs.

Write values through a narrow API, recalculate dependent formulas, and read the cells that determine the decision.

03 / save

Persist the workbook state.

Save WorkPaper JSON for route handlers, queue jobs, tests, tool integrations, and audit trails.

04 / bridge

Import or export XLSX when files matter.

Use the XLSX subpath and recalculation packages when the workflow still needs Excel-compatible files.

Quickstart

Run the WorkPaper loop first.

The fastest evaluation path is a real write, recalculate, read, save, and restore cycle from the published package.

No-clone command

terminal Node.js 22+

npm exec --yes --package @bilig/workpaper@latest -- \
  bilig-evaluate --door workpaper-service --json

Want a starter? Run npm create @bilig/workpaper@latest pricing-workpaper. Need a saved workbook file? Start with the workbook report.

workpaper-service.json runtime readback

{
  "door": "workpaper-service",
  "editedCell": "Inputs!B2",
  "dependentCell": "Summary!B2",
  "before": 24000,
  "after": 38400,
  "afterRestore": 38400,
  "verified": true
}

Where it runs

Put the workbook behind the code that owns the workflow.

Route handler, queue worker, CLI, or MCP server: load the workbook, edit cells, read results, and save state.

fit Use Bilig when the workbook is the rulebook. Good fit: pricing, payouts, approvals, imports, finance checks, and tools that need calculated readback. service Put WorkPaper behind a Node API. Load a WorkPaper, write inputs, read formula outputs, and save JSON without opening a spreadsheet app. tools Expose tools, not a spreadsheet screen. Use narrow read/write commands so automation can change cells and return the calculated answer. limits Review compatibility limits before a production switch. Bilig is a headless runtime, not a full Excel clone. The missing behavior stays public.

@bilig/workpaper service loop

const paper = WorkPaper.buildFromSheets(model)
paper.setCellContents(inputCell, 40)

const answer = paper.getCellDisplayValue(outputCell)
const saved = serializeWorkPaperDocument(exportWorkPaperDocument(paper))
const restored = createWorkPaperFromDocument(parseWorkPaperDocument(saved))

console.log({ answer, restored: restored.getCellDisplayValue(outputCell) })
ok formula readback
ok saved WorkPaper JSON
ok restored state

Compatibility

Compatibility stays explicit.

WorkPaper is the source of truth for workbook-shaped service logic. Saved XLSX files still need import and recalculation checks before production use.

workbook behavior gates Deterministic

import/recalc/export checked

Workbook behavior is gated by deterministic fixtures and evaluator readback. External spreadsheet engines are comparison tools, not public proof counters. Import risks stay visible before a service trusts a saved workbook.

Oracle: Excel oracle harness
Report: Workbook Compatibility Report
Files: XLSX formula recalculation
Bugs: Formula bug clinic
Limits: Compatibility gaps stay documented.

Inspect Workbook report Check Compatibility gaps Run XLSX recalculation

Start here

Pick the path that matches the job.

Start with WorkPaper when the service owns the rule. Use the XLSX path only when the file must remain the contract.

runtime Install the WorkPaper package. Use this when you want TypeScript control over workbook state. node Run a WorkPaper in a service. Create a starter, write an input, read a formula, save JSON, and restore it. tools Give tool hosts a workbook API. Expose cell reads, writes, formula readback, and persistence without screen automation. api Ship a small route around the runtime. Use the quote-approval example when the workbook logic belongs behind HTTP. xlsx Keep XLSX only when the file is the contract. Edit inputs, read recalculated values, and write a fresh workbook file. compat Review saved-workbook compatibility before import. Use the report when workbook files remain part of the workflow. fixture Turn one real workbook blocker into a public fixture. Start with the formula clinic, then send only reduced public cases. compare Check the alternatives before switching. Pick between browser grids, XLSX tooling, formula engines, and a WorkPaper runtime. limits Read the Excel gaps before importing real workbooks. Known missing behavior is listed before it surprises you. contribute Take a starter issue that improves the examples. Start with code/test picks, example tasks, adapters, or focused docs coverage.

Reference

Start narrow, then go deeper.

Choose by boundary. Use @bilig/workpaper when the service or tool host owns workbook state, and saved-file tools only when the file remains the contract.

Run

Build

Tool hosts

Tool host? Do not drive Excel, LibreOffice, Google Sheets, or a browser grid. Run npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json first.

Use @bilig/workbook only when a runtime needs transport-neutral plan data and command receipts.

Run workbook rules in Node.