Univer Node.js Backend

Run Univer without browser UI for data, document, presentation, Base, Board, and PDF automation.

Compatibility: Synced to the current Univer and Univer Pro source baseline, 1.0.0-beta.0. Keep every @univerjs/* and @univerjs-pro/* package on exactly the same version. The public OSS headless runtime supports Node.js >=18.17.0; developing the current Univer source checkout requires Node.js >=22.18 and pnpm >=10.

Public setup: Prefer createUniver with @univerjs/preset-sheets-node-core or @univerjs/preset-docs-node-core when either OSS preset fits. createUniverOnNode is the name of an example-local helper in the Univer repositories, not an exported npm API. The other four product hosts currently use manual Pro plugin stacks.

Choose the product path

Package existence, headless model/Facade support, browser rendering, and a maintained preset are separate facts:

Product	Current Node path	Verified current example boundary
Sheets	OSS UniverSheetsNodeCorePreset; manual Pro stack for licensed features	Local OSS workbooks; the Pro example loads a collaborative Sheet
Docs	OSS UniverDocsNodeCorePreset; manual Pro stack for licensed Docs features	Local document model through the OSS preset; the Pro example loads a collaborative Doc
Slides	Manual @univerjs-pro/slides stack and @univerjs-pro/slides/facade	The current Pro example loads a collaborative Slide
Bases	Manual @univerjs-pro/bases stack and @univerjs-pro/bases/facade; the current example pairs a Node formula worker	The current Pro example loads a collaborative Base
Boards	Manual @univerjs-pro/boards stack and @univerjs-pro/boards/facade	The current Pro example can call local createBoard(...) or load a collaborative Board
PDFs	Manual @univerjs-pro/pdfs stack and @univerjs-pro/pdfs/facade	The current Pro example loads a collaborative PDF and edits its model

Slides, Bases, Boards, and PDFs have no unified Node preset in the checked source. Their current Node examples register runtime/model plugins and Facade side effects without *-ui plugins or CSS. A registered render engine satisfies model dependencies in some examples; it does not establish browser canvas rendering, screenshots, print, or exchange-client support. Read the Node plugin registry and Pro Node.js integration before composing one of these hosts.

Quick Start

1. Install the current Node preset

npm install @univerjs/core@1.0.0-beta.0 @univerjs/presets@1.0.0-beta.0 @univerjs/preset-sheets-node-core@1.0.0-beta.0 rxjs@^7.8.2

2. Create and process a workbook

import { LocaleType } from '@univerjs/core';
import { UniverSheetsNodeCorePreset } from '@univerjs/preset-sheets-node-core';
import UniverSheetsNodeCoreEnUS from '@univerjs/preset-sheets-node-core/locales/en-US';
import { createUniver } from '@univerjs/presets';

const { univer, univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: UniverSheetsNodeCoreEnUS,
  },
  presets: [UniverSheetsNodeCorePreset()],
});

try {
  const workbook = univerAPI.createWorkbook({});
  const sheet = workbook.getActiveSheet();

  sheet.getRange('A1').setValue(123);
  sheet.getRange('B1').setValue('=SUM(A1) * 6');
  await univerAPI.getFormula().onCalculationResultApplied();

  console.log(sheet.getRange('B1').getValue()); // 738
  console.log(workbook.save());
} finally {
  univer.dispose();
}

The preset registers the core Sheets, formula, data-validation, filter, hyperlink, drawing, sort, and thread-comment plugins plus their Node-safe Facade extensions.

Formula Worker

Pass a built JavaScript worker path to the preset. @univerjs/rpc-node uses node:child_process.fork(), not a browser Worker.

// main.ts (ESM)
import { fileURLToPath } from 'node:url';
import { LocaleType } from '@univerjs/core';
import { UniverSheetsNodeCorePreset } from '@univerjs/preset-sheets-node-core';
import UniverSheetsNodeCoreEnUS from '@univerjs/preset-sheets-node-core/locales/en-US';
import { createUniver } from '@univerjs/presets';

const workerSrc = fileURLToPath(new URL('./formula-worker.js', import.meta.url));
const { univer, univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: UniverSheetsNodeCoreEnUS,
  },
  presets: [UniverSheetsNodeCorePreset({ workerSrc })],
});

// formula-worker.ts; compile it to formula-worker.js before running main.ts
import { LocaleType } from '@univerjs/core';
import { UniverSheetsNodeCoreWorkerPreset } from '@univerjs/preset-sheets-node-core/worker';
import { createUniver } from '@univerjs/presets';

createUniver({
  locale: LocaleType.EN_US,
  presets: [UniverSheetsNodeCoreWorkerPreset()],
});

The worker preset includes UniverRPCNodeWorkerPlugin and UniverRemoteSheetsFormulaPlugin. Do not replace the latter with the main-thread UniverSheetsFormulaPlugin.

Node-Specific Rules

Concern	Browser	Node.js
Setup	Browser preset or manual UI plugins	Sheets/Docs Node preset, or a source-verified manual Pro product stack
UI	UniverUIPlugin, *-ui, CSS	Omit
RPC main	UniverRPCMainThreadPlugin with workerURL	UniverRPCNodeMainPlugin with workerSrc
RPC worker	UniverRPCWorkerThreadPlugin	UniverRPCNodeWorkerPlugin
Formula worker bridge	UniverRemoteSheetsFormulaPlugin	UniverRemoteSheetsFormulaPlugin
Theme	Runtime theme and CSS required for UI	Not needed for data-only processing

Facade imports

The Sheets Node preset loads its documented Facade side effects. The Docs Node preset loads only the formula Facade; import @univerjs/docs/facade before calling createDocument(...). With manual registration, import the Facade entry for every API surface used and exclude @univerjs/ui/facade and *-ui/facade. Read the Node plugin registry before assembling a manual plugin or Facade list.

Pro on Node.js

For the six-product Pro Node matrix, exact runtime/Facade stacks, formula and Base workers, model-only chart/shape boundaries, and collaboration, read Pro Node.js integration.

References

• Node plugin registry — six-product support matrix, current preset contents, manual plugins, Facade allowlist, worker pairing, and browser-only exclusions
• Node common tasks — batch reports, JSON snapshots, formula barriers, custom functions, events, and resource cleanup
• Pro Node.js integration — exact six-product Pro stacks, formula/Base workers, collaboration socket adapter, license handling, and current headless limitations