@namahapdf/sheets - In-Browser Excel (.xlsx) Engine for JavaScript

@namahapdf/sheets is a headless Excel engine that runs entirely in the browser

• parse and render .xlsx on a virtualized canvas grid, edit cells with faithful write-back, and project a workbook into an AI-readable model. It's an in-house OOXML implementation (no LibreOffice, no cloud conversion service) built to open, display, and edit real spreadsheets client-side, with no repair dialog when the edited file is reopened in Excel.

Live demo · Full docs · Get a license

npm i @namahapdf/sheets

import { XlsxEditSession, SheetRenderer, configureLicense } from '@namahapdf/sheets';

// Apply your license key (without one, exports are watermarked + features limited).
configureLicense({ licenseKey: 'YOUR_KEY' });

// Load a workbook into an editing session, edit by intents, save a faithful .xlsx.
const session = await XlsxEditSession.load('book.xlsx', bytes);
await session.apply([
  { op: 'set-cell', anchor: { fmt: 'xlsx', sheetPart: 'xl/worksheets/sheet1.xml', row: 1, col: 1 }, row: 1, col: 1, newText: '5000000' },
  { op: 'format-cell', anchor: { fmt: 'xlsx', sheetPart: 'xl/worksheets/sheet1.xml', row: 1, col: 1 }, row: 1, col: 1, format: { bold: true, numFmt: '$#,##0.00' } },
]);
const editedBytes = session.bytes;              // still a valid .xlsx

Features

• Parser - .xlsx → a sparse SheetModel (resolved styles, merges, number formats), fully client-side
• Renderer - a viewport-only virtualized canvas grid that scales to 100k+ rows, frozen headers, merge-aware
• Faithful write-back - edits apply as surgical XML splices on the original package, so everything an edit doesn't touch is preserved byte-for-byte
• Formulas that compute - a whitelisted in-browser evaluator (~50 functions, refs/ranges incl. cross-sheet, dependency-ordered recalc) writes both <f> and a cached <v>, so cells show their result immediately. Anything outside the whitelist is flagged, never guessed
• Recalc-safe by construction - every value edit still sets fullCalcOnLoad and drops the cached calc chain, so Excel owns the math: a value we compute is display-only and can never make a workbook wrong
• Rows, columns and fill - insert/delete rows and columns move cell refs, widths, merges and formulas workbook-wide; fillCells reproduces Excel's drag-to-fill series (trend, dates, weekday/month lists, translated formulas)
• AI-ready - a small, JSON-serializable EditPlan vocabulary (set-cell, clear-cell, format-cell, set-column-width, insert-rows, …); validate with validateEditPlan and the same plan an LLM emits is the plan the UI emits
• TypeScript-first, ESM + CJS builds

Why teams pick @namahapdf/sheets

Client-side spreadsheet editing is rare. Most document SDKs that touch Excel files are view-only or lean on a server. @namahapdf/sheets edits and re-saves a real .xlsx entirely in the browser.

Round-trip fidelity by construction. The parsed SheetModel is a render view, not the source of truth - the writer always re-opens the original zip/XML and splices only what an EditPlan intent changed, so untouched sheets, styles, and formulas are byte-identical to the source file.

On-device by architecture. Parsing, rendering, and editing all run client-side - no upload step, no cloud dependency for the common path.

One intent vocabulary for humans and AI. The UI and an LLM agent emit the exact same EditPlan JSON against the exact same apply path - there's no separate, riskier "AI editing" code path to maintain or trust.

API surface

• XlsxDocument - .xlsx → a sparse SheetModel (styles, merges, number formats, formulas + cached values)
• SheetRenderer - a viewport-only virtualized canvas grid
• applyXlsxPlan / XlsxEditSession - write-back (intent-sourced, undo/redo)
• evaluateFormula / recalcSheet / FORMULA_FUNCTIONS - the formula engine (extend the registry with one entry)
• translateFormula - relative-reference shifting for copy/fill
• detectSeries / fillCells - Excel's fill-handle heuristics, as pure functions
• formatValue - the in-house number-format subset (currency, %, dates, …)

The full API reference and edit-intent contract live in the Excel SDK docs.

Licensing

Free to install and use - trial mode renders a watermark and gates premium features. A per-domain license key removes the watermark and unlocks the full feature set. Get one at pdf.namahatech.com/sdk; pricing at pdf.namahatech.com/pricing. A ready-made React sheet editor (@namahapdf/react) is planned.

Related packages

| Package | What it is | |---|---| | @namahapdf/sheets | This package - the headless Excel engine | | @namahapdf/core | Headless PDF engine | | @namahapdf/pptx | Headless PowerPoint (.pptx) engine | | @namahapdf/react | React <NamahaEditor> (PDF today) |

FAQ

Does this upload spreadsheets to a server? No. Parsing, rendering, and editing all run in the browser. Nothing is uploaded for the common path.

Does it evaluate formulas? Yes, for a deliberately bounded whitelist (~50 functions: arithmetic, refs and ranges including cross-sheet, SUM/IF/VLOOKUP/TEXT/date families). Results are written as both <f> and a cached <v>, so cells display immediately. Array formulas, volatile functions, external refs and iterative calc are out of scope: those cells keep the value Excel last cached and needsExcelRecalc() reports them. Because every value edit marks the workbook for fullCalcOnLoad, Excel recalculates everything on open - so anything we decline to compute is deferred, never wrong.

Will edited workbooks open in Excel without a repair-dialog warning? Yes - that's the core design constraint. Write-back is byte-preserving on anything an EditPlan doesn't explicitly touch; npm run audit:xlsx in the source repo is the fidelity regression gate.

Can an LLM agent edit a spreadsheet with this? Yes - EditPlan is a small, Zod-validated JSON schema designed to be handed to an LLM as a tool definition; the agent emits the same intents the UI does.

Is there a free tier? Yes. It's free to install and use in trial mode (watermarked, feature-limited). See pdf.namahatech.com/pricing for licensed tiers.

License: proprietary (see LICENSE). A license key from pdf.namahatech.com/sdk removes the trial watermark for production use. Questions or enterprise inquiries: same link.