univer-node-backend

# Univer Node.js Backend Guide for running Univer in Node.js environments without a browser. Use this for headless spreadsheet processing, automated report generation, server-side formula calculation, and batch data manipulation. > **Compatibility**: This skill is written for Univer `v0.21.x` / Univer Pro `v0.20.x`. Node.js support is isomorphic with browser support per the Univer architecture. > **Prerequisites**: Familiarity with the `univer-integrate` skill (base plugin architecture, Facade API, plugin registration order) is assumed. This skill only covers Node.js-specific differences. ## Quick Start ### 1. Install dependencies ```bash npm install @univerjs/core @univerjs/engine-formula @univerjs/sheets @univerjs/sheets-formula @univerjs/rpc-node ``` For Pro features in Node.js: ```bash npm install @univerjs-pro/license @univerjs-pro/engine-formula @univerjs-pro/sheets-pivot @univerjs-pro/collaboration-client-node ``` ### 2. Create Univer instance on Node.js ```ts import { LocaleType, Univer } from '@univerjs/core'; import { FUniver } from '@univerjs/core/facade'; import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'; import { UniverSheetsPlugin } from '@univerjs/sheets'; import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula'; import { UniverSheetsFilterPlugin } from '@univerjs/sheets-filter'; // Facade side-effect imports for Node.js import '@univerjs/sheets/facade'; import '@univerjs/engine-formula/facade'; import '@univerjs/sheets-formula/facade'; import '@univerjs/sheets-filter/facade'; import '@univerjs/sheets-numfmt/facade'; const univer = new Univer({ locale: LocaleType.ZH_CN, }); univer.registerPlugin(UniverFormulaEnginePlugin); univer.registerPlugin(UniverSheetsPlugin); univer.registerPlugin(UniverSheetsFormulaPlugin); univer.registerPlugin(UniverSheetsFilterPlugin); const univerAPI = FUniver.newAPI(univer); const workbook = univerAPI.createWorkbook({}); const sheet = workbook.getActiveSheet(); sheet.getRange('A1').setValue({ v: 123 }); sheet.getRange('B1').setValue({ f: '=SUM(A1) * 6' }); console.log(workbook.save()); ``` ### 3. Node.js worker for formula computing (optional) For heavy formula workloads, offload to a forked process: ```ts // main.ts import path from 'node:path'; import { LocaleType, Univer } from '@univerjs/core'; import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'; import { UniverRPCNodeMainPlugin } from '@univerjs/rpc-node'; import { UniverSheetsPlugin } from '@univerjs/sheets'; const univer = new Univer({ locale: LocaleType.ZH_CN }); univer.registerPlugin(UniverFormulaEnginePlugin, { notExecuteFormula: true }); univer.registerPlugin(UniverSheetsPlugin); const workerPath = path.join(__dirname, 'worker.js'); univer.registerPlugin(UniverRPCNodeMainPlugin, { workerSrc: workerPath }); ``` ```ts // worker.js import { LocaleType, Univer } from '@univerjs/core'; import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'; import { UniverRPCNodeWorkerPlugin } from '@univerjs/rpc-node'; import { UniverSheetsPlugin } from '@univerjs/sheets'; const univer = new Univer({ locale: LocaleType.ZH_CN }); univer.registerPlugin(UniverSheetsPlugin, { onlyRegisterFormulaRelatedMutations: true }); univer.registerPlugin(UniverFormulaEnginePlugin); univer.registerPlugin(UniverRPCNodeWorkerPlugin); ``` ## Core Concepts ### Browser vs Node.js Differences | Concern | Browser | Node.js | |---------|---------|---------| | UI plugins | Required (`UniverUIPlugin`, `*-ui`) | **Omit all `*-ui` plugins** | | Render engine | `UniverRenderEnginePlugin` | Omit unless using chart/shape | | RPC | `UniverRPCMainThreadPlugin` + `Worker` | `UniverRPCNodeMainPlugin` + `fork()` | | Worker plugin | `UniverRPCWorkerThreadPlugin` | `UniverRPCNodeWorkerPlugin` | | CSS imports | Required | **Not needed** | | Theme | `defaultTheme` from `@univerjs/themes` | **Not needed** | ### Plugin Registration Order (Node.js) ``` 1. UniverLicensePlugin (Pro only) 2. Engine plugins (UniverFormulaEnginePlugin / UniverProFormulaEnginePlugin) 3. RPC (UniverRPCNodeMainPlugin, if using worker) 4. Unit core (UniverSheetsPlugin, UniverDocsPlugin) 5. Feature plugins (UniverSheetsFormulaPlugin, UniverSheetsFilterPlugin, etc.) 6. Pro features (UniverSheetsPivotTablePlugin, etc.) ``` ### Node.js Facade Imports Not all facade imports work in Node.js. Only import packages that do not depend on browser APIs: ```ts // Safe in Node.js import '@univerjs/core/facade'; import '@univerjs/sheets/facade'; import '@univerjs/engine-formula/facade'; import '@univerjs/sheets-formula/facade'; import '@univerjs/sheets-filter/facade'; import '@univerjs/sheets-numfmt/facade'; import '@univerjs/sheets-data-validation/facade'; import '@univerjs/sheets-conditional-formatting/facade'; import '@univerjs/sheets-hyper-link/facade'; import '@univerjs/sheets-thread-comment/facade'; import '@univerjs/sheets-drawing/facade'; import '@univerjs/sheets-sort/facade'; import '@univerjs/sheets-table/facade'; import '@univerjs/sheets-note/facade'; // Pro (safe in Node.js) import '@univerjs-pro/sheets-pivot/facade'; import '@univerjs-pro/sheets-chart/facade'; import '@univerjs-pro/sheets-shape/facade'; import '@univerjs-pro/sheets-sparkline/facade'; import '@univerjs-pro/collaboration-client/facade'; // Unsafe in Node.js (depend on browser APIs) // import '@univerjs/ui/facade'; // import '@univerjs/sheets-ui/facade'; // import '@univerjs/sheets-drawing-ui/facade'; // import '@univerjs/sheets-formula-ui/facade'; ``` ## Common Tasks ### Batch Report Generation ```ts const workbook = univerAPI.createWorkbook({}); const sheet = workbook.getActiveSheet(); // Populate data from database const rows = await db.query('SELECT * sales'); rows.forEach((row, i) => { sheet.getRange(i + 1, 0).setValue(row.date); sheet.getRange(i + 1, 1).setValue(row.amount); }); // Add formula summary const lastRow = rows.length; sheet.getRange(lastRow + 1, 1).setValue({ f: `=SUM(B2:B${lastRow})` }); // Export snapshot const snapshot = workbook.save(); ``` ### Load and Modify Existing Workbook ```ts const existingData = JSON.parse(fs.readFileSync('input.json', 'utf8')); const workbook = univerAPI.createWorkbook(existingData); const sheet = workbook.getActiveSheet(); sheet.getRange('A1').setValue('Updated'); fs.writeFileSync('output.json', JSON.stringify(workbook.save())); ``` ### Server-Side Formula Calculation ```ts // Without worker (simple workloads) univer.registerPlugin(UniverFormulaEnginePlugin); // With worker (heavy workloads) univer.registerPlugin(UniverFormulaEnginePlugin, { notExecuteFormula: true }); univer.registerPlugin(UniverRPCNodeMainPlugin, { workerSrc: './worker.js' }); ``` ### Register Custom Function on Server ```ts const formulaEngine = univerAPI.getFormula(); formulaEngine.registerFunction( 'DISCOUNT', (price, percent) => price * (1 - percent / 100), 'Calculate price after discount' ); ``` ## Pro Node.js Integration For using Univer Pro features (collaboration, pivot, chart, shape) in Node.js, see `references/node-pro-integration.md`. ## References - **Node plugin registry**: `references/node-plugin-registry.md` — complete plugin list for Node.js, registration order, worker configuration, and browser-only exclusions - **Node common tasks**: `references/node-common-tasks.md` — batch processing, JSON import/export, formula calculation patterns, custom functions, event handling in headless mode - **Pro Node.js integration**: `references/node-pro-integration.md` — Pro formula engine, collaboration client node, pivot/chart/shape in backend, license setup for server