DocumentationServerWhy

Why Jspreadsheet Server

ULTIMATE

A spreadsheet that several people edit at once, that your backend can read and write, that an AI can work on, and that keeps every change in your own database, takes much more than a browser grid. This page lists what it takes, so you can compare building it with using Jspreadsheet Server.

What a collaborative spreadsheet needs

Capability What it involves In Jspreadsheet Server
Ordering Every client edits optimistically; someone must decide the order in which edits apply, and every client must converge to it A central sequencer per document assigns a revision to each operation. See Sync & conflicts
Conflicts Two users change the same cell, insert rows at the same time, or undo across each other Last-write-wins at cell level; every client replays the same sequence and converges; undo is personal and never reverts another user's edit
Reconnection A laptop sleeps, a train enters a tunnel; the client must catch up without corrupting the document Revision tracking and version signatures; a client that missed operations reloads to the server state
The live document Formulas, styles, merges, tables, validations and charts have to be applied on the server exactly as in the browser The same Jspreadsheet engine runs headless on the server
Formulas A server that only stores raw values cannot answer "what is the total" 500+ functions computed server side, so APIs and AI read calculated values
Persistence Saving the whole document on every keystroke does not scale; saving operations needs a translation per method Per-operation adapters for MongoDB, PostgreSQL and Redis, or your own five handlers
Memory Thousands of documents cannot all stay loaded Lazy loading, idle eviction and a cap on cached documents. See Architecture
Access control Who may open, edit, share or delete each document Three hooks with your own identity: beforeConnect, beforeLoad, beforeChange. See Authentication
Sharing Invitations, read-only links, public and private documents Sharing & privacy
An API Backend jobs, imports and integrations need to read and write cells without a browser A REST API over every worksheet module. See Routes
History Point-in-time copies and restore Snapshots
Files Images in cells and charts should not live inside the document Images & media to S3 or your storage
Comments Threaded cell comments, synchronized and persisted Comments
Forms Collect data into a spreadsheet from a public form Formify
AI An assistant that edits the live document, external AI clients, AI in formulas, and budgets AI agent, MCP server, PROMPT, usage & billing
Scale More documents than one process holds Partition by document with a consistent hash, no coordination layer. See Scaling

The hard parts are not the obvious ones

A WebSocket and a broadcast work in a demo. The effort goes into what comes after:

  • Spreadsheet semantics on the server. A spreadsheet operation is "insert two rows above row 7 in Sheet2", and its effect on formulas, merges, styles and references must be identical on every client and on the server. That requires running the spreadsheet engine on the server, not just relaying JSON.
  • Persistence that keeps up. Writing the full document per change collapses with document size. Persisting operations means mapping every method (setValue, insertRow, setStyle, setMerge...) to an incremental update of your storage, and keeping that mapping correct as the product grows.
  • The long tail of conflicts. Concurrent row inserts, an undo of an edit someone else has since changed, a paste over a range another user is filtering. Each is rare and each corrupts data when it goes wrong.
  • Everything around the editor. Authentication, sharing, an API, file storage, snapshots, monitoring and AI.

What you keep control of

  • Your database. Documents live in the storage you already run, through an adapter. Nothing is stored anywhere else.
  • Your users. The server has no user table. Your hooks receive the token of each request and decide.
  • Your infrastructure. It is a Node.js package you deploy where you want: your cloud, your data center, a network with no internet access.
  • Your AI provider. Model keys stay in server config; you choose the model and the budget.

Use the parts you need

A minimal collaborative backend is the core and a persistence handler; everything else is an extension you add when needed:

const server = require('@jspreadsheet/server');
const api = require('@jspreadsheet/server-api');
const adapter = require('@jspreadsheet/server-mongodb');
const agent = require('@jspreadsheet/server-agent');
const mcp = require('@jspreadsheet/mcp');

server({
    // Who may do what, with your identity
    beforeConnect: async (auth) => true,
    beforeLoad: async (guid, auth) => true,
    beforeChange: async (guid, changes, auth) => true,
    // Where documents live
    load: (guid, auth) => adapter.load(guid, auth),
    create: (guid, config, auth) => adapter.create(guid, config, auth),
    change: (guid, changes, auth, onerror) => adapter.change(guid, changes, auth, onerror),
    destroy: (guid, auth) => adapter.destroy(guid, auth),
    replace: (guid, config, auth) => adapter.replace(guid, config, auth),
    // What else the product needs
    extensions: { api, agent, mcp },
    license: { clientId, licenseKey },
});

Where to go next