Headless and server-side calculation

Run content operations in Node.js, use Rust for precomputation, and give agents structured and visual results.

Headless Univer is Univer’s content runtime without an interactive editor UI. It shares content models, commands, calculation, and Facade APIs with the browser editor. It can process content in Node.js or run UI-free tasks in a browser. Available capabilities depend on the registered product and feature plugins.

The JavaScript/TypeScript content runtime described here and univer-rs are separate execution implementations. The latter supports server-side calculation and file conversion and can be combined with Headless workflows around the same snapshots.

What Headless can do

  • Read and change content and structure: create or load Univer snapshots, use Facade APIs to read and edit cells, paragraphs, pages, graphical objects, or records, then save updated snapshots. This supports batch processing, data generation, content inspection, and agent automation.
  • Run registered business logic: use formula calculation, sorting, filtering, validation, and pivot plugins; modify resources such as images, charts, shapes, and comments. Available operations depend on the product and feature plugins and their dependencies.
  • Connect to other services: add the Node.js collaboration client to load collaborative Units, submit changes, and wait for synchronization; combine Server SDK conversion modules with the runtime to import and export Office files.

Headless itself does not provide menus, toolbars, dialogs, mouse or keyboard interaction, screenshots, or printing. It does not automatically provide persistence, authentication, a collaboration server, or file conversion. save() returns a Univer snapshot; it does not write to a database or export XLSX, DOCX, or PDF. Screenshots and visual layout checks require a separate rendering runtime; a headless browser still runs the rendering layer.

Which packages belong to Headless

Choose the content packages you need, then register their product plugins and dependencies. Configure the required licenses for Pro features.

Content models

Instances, content models, commands, and basic content operations.

  • @univerjs/core
  • @univerjs/sheets
  • @univerjs/docs

Formulas and number formats

Formula execution, Sheet formula integration, and number formatting; choose the open-source or Pro engine for the required features.

  • @univerjs/engine-formula
  • @univerjs/sheets-formula
  • @univerjs/sheets-numfmt
  • @univerjs-pro/engine-formula

Sheet data and rules

Sheet data and rule operations, without the corresponding panels or visual interaction. Data validation also requires @univerjs/data-validation.

  • @univerjs/sheets-filter
  • @univerjs/sheets-sort
  • @univerjs/sheets-conditional-formatting
  • @univerjs/sheets-data-validation
  • @univerjs/sheets-table
  • @univerjs/sheets-hyper-link
  • @univerjs/sheets-note

Models, resources, and commands for images, links, and comments; connect display, uploads, and external data sources separately as needed.

  • @univerjs/drawing
  • @univerjs/sheets-drawing
  • @univerjs/docs-drawing
  • @univerjs/docs-hyper-link
  • @univerjs/thread-comment
  • @univerjs/sheets-thread-comment
  • @univerjs/docs-thread-comment

Advanced Sheet features

Content and calculation logic for pivots, charts, shapes, sparklines, outlines, and slicers; graphical dependencies can include @univerjs-pro/engine-chart and @univerjs-pro/engine-shape.

  • @univerjs-pro/sheets-pivot
  • @univerjs-pro/sheets-chart
  • @univerjs-pro/sheets-shape
  • @univerjs-pro/sheets-sparkline
  • @univerjs-pro/sheets-outline
  • @univerjs-pro/sheets-slicer

Document extensions

Content operations for document blocks, tables, columns, formulas, and shapes, without editor controls.

  • @univerjs-pro/docs-callout
  • @univerjs-pro/docs-code
  • @univerjs-pro/docs-list
  • @univerjs-pro/docs-quote
  • @univerjs-pro/docs-table
  • @univerjs-pro/docs-column
  • @univerjs-pro/docs-latex
  • @univerjs-pro/docs-formula
  • @univerjs-pro/docs-shape

Other product models

Models and commands for other products. pdfs-editor configures PDF editor lifecycle and collaboration integration: editor in a package name does not imply UI. Available APIs vary by product.

  • @univerjs-pro/slides
  • @univerjs-pro/bases
  • @univerjs-pro/boards
  • @univerjs-pro/pdfs
  • @univerjs-pro/pdfs-editor

Networking, computation processes, and collaboration

Add infrastructure as needed: @univerjs/network and @univerjs/rpc-node provide networking and Node.js computation processes; @univerjs-pro/license handles license integration. @univerjs-pro/collaboration, @univerjs-pro/collaboration-client, and @univerjs-pro/collaboration-client-node can form a Headless collaboration client, not a collaboration server. Processing local snapshots independently does not require a collaboration service.

Packages outside a content-only runtime

  • @univerjs/ui, @univerjs/design, and product or feature *-ui packages, such as @univerjs/sheets-ui, @univerjs/docs-ui, and @univerjs-pro/slides-ui, provide UI, rendering integration, or interaction. Do not add them to a pure Node.js content-processing configuration.
  • @univerjs/sheets-find-replace and @univerjs/sheets-crosshair-highlight depend on @univerjs/sheets-ui despite lacking a -ui suffix. Their names do not make them Headless plugins.
  • The default @univerjs/preset-sheets-core and @univerjs/preset-docs-core presets register UI plugins. They are not Node.js Headless presets; use plugin mode to select content-layer dependencies explicitly.

Treat @univerjs/engine-render separately. Current Node.js examples register it to supply shared dependencies such as render management. Registering the plugin does not create a Canvas or mount an editor. It can appear in a Headless composition, but drawing, font measurement, and screenshot APIs still need a suitable rendering environment. This does not make every API in the package usable in pure Node.js.

Facade is an operation API, not an environment adapter. Import the required content plugins’ /facade extensions and register the plugins that implement those capabilities. UI extensions such as @univerjs/ui/facade and @univerjs/sheets-ui/facade, including menus, scrolling, and visual selection interactions, still require UI. Check plugin dependencies and the actual call path rather than relying on a package name or the presence of Facade APIs.

See the Sheets Headless guide and Docs Headless guide for runnable plugin compositions.

Immediate frontend calculation, versioned server calculation

Both the frontend and server have formula engines. The frontend responds to editing; the server calculates a captured content revision when generating a snapshot or processing a file.

  • While editing: the browser calculates affected formulas locally, optionally in a Worker, and displays results immediately. Collaboration records and synchronizes content changes.
  • When generating a snapshot: the server’s snapshot policy triggers the save workflow. The server captures the content revision for this operation, calculates with univer-rs, then saves that revision’s content and results together.
  • When reopening: the frontend reuses valid results in the snapshot, applies later changes, and continues calculating, reducing repeated full calculation.
100%

Content changes synchronize continuously. Server calculation runs as part of snapshot generation, with results saved for that content revision.

Configure initial calculation to match the saved results:

  • WHEN_EMPTY: reuse stored formula values and calculate only missing results.
  • NO_CALCULATION: skip initial formula calculation when the application supplies the results.
  • FORCED: recalculate all formulas when stored results need refreshing.

These options control initial loading. Subsequent editing continues to calculate in the frontend; the server calculates on demand when generating a versioned snapshot or processing files. See formula configuration, collaboration, and file conversion.

Formula engine performance

See the Univer Rust formula engine benchmarks for 10 workbooks, including Rust input loading, stage timings, input-format boundaries and workbook downloads.

Array formulas and spill results

Within the supported functions and formats, Rust follows Excel’s array-formula and spill semantics. It returns calculated values together with the anchor and spill range, including dynamic arrays and declared ranges for legacy array formulas.

For example, =SEQUENCE(3,2) in an empty A1 produces:

AB
12
34
56

The formula remains in A1; results occupy A1:B3. When an array shrinks, old spill values are cleared. A blocked spill reports #SPILL!. The browser, agent, and export pipeline can reuse the calculated snapshot.

See formula support and Excel array behavior for the corresponding function and range rules.

Connect the runtime to an agent

Keep your existing model, conversation, and tool orchestration. AI SDK tools expose Office content operations to that agent:

  1. Inspect structure and read the target content.
  2. Apply Facade changes and run the required calculations in the headless runtime.
  3. Wait for calculation and commit confirmation, then read back the updated state.
  4. Check values and structure; add screenshots or layout checks when visual verification is needed.

Use content operations and visual inspection together. For human review, place edits in a Worktree before comparison and merge. Univer CLI demonstrates how to assemble these capabilities into an agent-facing application.

Integration paths

CapabilityWhat it enables
Node.js content runtimeStart with headless Univer and enable the product and calculation plugins you need.
Background file processingCombine Rust calculation with Node.js file conversion, then save or return the updated snapshot.
Shared editing and agentsConnect collaboration and AI SDK so people and agents operate on confirmed content.

Back to all features

How is this guide?

© 2026 DreamNum Co., Ltd.