Univer Node Backend

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:

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

bashCopy code
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

tsCopy code
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.

tsCopy code
// 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 })],
});

tsCopy code
// 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

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