univer-pro-integrate

Univer Pro Integrate

Guide for embedding Univer Pro into existing web applications. Univer Pro extends open-source Univer with enterprise features including collaboration, import/export, printing, pivot tables, charts, sparklines, shapes, and license management.

Compatibility: This skill is written for Univer Pro v0.20.x. Core concepts remain stable across minor versions, but specific method signatures may shift. Check the user's installed @univerjs-pro/* versions and prefer their project's existing API patterns.

Prerequisites: Univer Pro requires the open-source Univer core. See the univer-integrate skill for base integration patterns (initialization, Facade API, plugin architecture) before applying Pro features.

Quick Start

1. Install Pro dependencies

npm install @univerjs-pro/license @univerjs-pro/engine-formula @univerjs-pro/sheets-pivot @univerjs-pro/sheets-pivot-ui @univerjs-pro/sheets-chart @univerjs-pro/sheets-chart-ui @univerjs-pro/sheets-sparkline @univerjs-pro/sheets-sparkline-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-ui @univerjs-pro/sheets-print @univerjs-pro/exchange-client @univerjs-pro/sheets-exchange-client

For collaboration:

npm install @univerjs-pro/collaboration @univerjs-pro/collaboration-client @univerjs-pro/collaboration-client-ui

2. Register core Pro plugins

import { LocaleType, Univer, UniverInstanceType } from '@univerjs/core';
import { FUniver } from '@univerjs/core/facade';
import { UniverRenderEnginePlugin } from '@univerjs/engine-render';
import { UniverUIPlugin } from '@univerjs/ui';
import { UniverSheetsPlugin } from '@univerjs/sheets';
import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui';
import { UniverRPCMainThreadPlugin } from '@univerjs/rpc';
import { defaultTheme } from '@univerjs/themes';

// Pro plugins
import { UniverLicensePlugin } from '@univerjs-pro/license';
import { UniverProFormulaEnginePlugin } from '@univerjs-pro/engine-formula';
import { UniverSheetsPivotTablePlugin } from '@univerjs-pro/sheets-pivot';
import { UniverSheetsPivotTableUIPlugin } from '@univerjs-pro/sheets-pivot-ui';
import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart';
import { UniverSheetsChartUIPlugin } from '@univerjs-pro/sheets-chart-ui';
import { UniverSheetSparklinePlugin } from '@univerjs-pro/sheets-sparkline';
import { UniverSheetSparklineUIPlugin } from '@univerjs-pro/sheets-sparkline-ui';
import { UniverSheetsShapePlugin } from '@univerjs-pro/sheets-shape';
import { UniverSheetsShapeUIPlugin } from '@univerjs-pro/sheets-shape-ui';
import { UniverSheetsPrintPlugin } from '@univerjs-pro/sheets-print';
import { UniverExchangeClientPlugin } from '@univerjs-pro/exchange-client';
import { UniverSheetsExchangeClientPlugin } from '@univerjs-pro/sheets-exchange-client';

// Facade side-effect imports (Pro)
import '@univerjs-pro/sheets-pivot/facade';
import '@univerjs-pro/engine-formula/facade';
import '@univerjs-pro/sheets-chart/facade';
import '@univerjs-pro/sheets-sparkline/facade';
import '@univerjs-pro/sheets-shape/facade';
import '@univerjs-pro/sheets-print/facade';
import '@univerjs-pro/exchange-client/facade';

const worker = new Worker(new URL('./worker.js', import.meta.url), { type: 'module' });

const univer = new Univer({
  theme: defaultTheme,
  locale: LocaleType.ZH_CN,
});

// License first
univer.registerPlugin(UniverLicensePlugin, {
  license: process.env.CLIENT_LICENSE_TEXT, // or your license string
});

univer.registerPlugins([
  [UniverRenderEnginePlugin],
  [UniverProFormulaEnginePlugin, { notExecuteFormula: true }],
  [UniverUIPlugin, { container: 'app' }],
  [UniverRPCMainThreadPlugin, { workerURL: worker }],
  [UniverSheetsPlugin, { notExecuteFormula: true }],
  [UniverSheetsUIPlugin],
  // Pro features
  [UniverSheetsPivotTablePlugin, { notExecuteFormula: true }],
  [UniverSheetsPivotTableUIPlugin],
  [UniverSheetsChartPlugin],
  [UniverSheetsChartUIPlugin],
  [UniverSheetSparklinePlugin],
  [UniverSheetSparklineUIPlugin],
  [UniverSheetsShapePlugin],
  [UniverSheetsShapeUIPlugin],
  [UniverSheetsPrintPlugin],
  [UniverExchangeClientPlugin, {
    uploadFileServerUrl: 'https://your-server/universer-api/stream/file/upload',
    getTaskServerUrl: 'https://your-server/universer-api/exchange/task/{taskID}',
    signUrlServerUrl: 'https://your-server/universer-api/file/{fileID}/sign-url',
    importServerUrl: 'https://your-server/universer-api/exchange/{type}/import',
    exportServerUrl: 'https://your-server/universer-api/exchange/{type}/export',
    downloadEndpointUrl: 'https://your-server/',
  }],
  [UniverSheetsExchangeClientPlugin],
]);

univer.createUnit(UniverInstanceType.UNIVER_SHEET, {});
const univerAPI = FUniver.newAPI(univer);

3. Pro Worker Setup

The Pro worker must include UniverProFormulaEnginePlugin, UniverLicensePlugin, and UniverSheetsPivotTablePlugin:

// worker.js
import { LocaleType, LogLevel, Univer } from '@univerjs/core';
import { UniverRPCWorkerThreadPlugin } from '@univerjs/rpc';
import { UniverSheetsPlugin } from '@univerjs/sheets';
import { UniverRemoteSheetsFormulaPlugin } from '@univerjs/sheets-formula';
import { UniverSheetsFilterPlugin } from '@univerjs/sheets-filter';

import { UniverLicensePlugin } from '@univerjs-pro/license';
import { UniverProFormulaEnginePlugin } from '@univerjs-pro/engine-formula';
import { UniverSheetsPivotTablePlugin } from '@univerjs-pro/sheets-pivot';

const univer = new Univer({
  locale: LocaleType.ZH_CN,
  logLevel: LogLevel.VERBOSE,
});

univer.registerPlugin(UniverLicensePlugin, {
  license: process.env.CLIENT_LICENSE_TEXT,
});
univer.registerPlugin(UniverSheetsPlugin, { onlyRegisterFormulaRelatedMutations: true });
univer.registerPlugin(UniverProFormulaEnginePlugin);
univer.registerPlugin(UniverRPCWorkerThreadPlugin);
univer.registerPlugin(UniverRemoteSheetsFormulaPlugin);
univer.registerPlugin(UniverSheetsFilterPlugin);
univer.registerPlugin(UniverSheetsPivotTablePlugin, { notExecuteFormula: false });

self.univer = univer;

Core Concepts

License-First Registration

UniverLicensePlugin must be registered immediately after creating the Univer instance, before any other Pro plugins. Without a valid license, Pro features run in evaluation mode (watermark, size limits, collaboration quotas).

Pro Formula Engine

Univer Pro replaces the open-source formula engine with UniverProFormulaEnginePlugin. Register it instead of UniverFormulaEnginePlugin when using Pro. It supports advanced functions required by pivot tables and server-side computing.

Plugin Registration Order

The order for Pro integrations is:

1. UniverLicensePlugin
2. Engine plugins (UniverRenderEnginePlugin, UniverProFormulaEnginePlugin)
3. UI infrastructure (UniverUIPlugin, UniverRPCMainThreadPlugin)
4. Unit core (UniverSheetsPlugin, UniverDocsPlugin)
5. Unit UI (UniverSheetsUIPlugin, UniverDocsUIPlugin)
6. Pro features (pivot, chart, sparkline, shape, print, exchange)
7. Collaboration features (if needed)

Version Policy

All @univerjs/* and @univerjs-pro/* packages must be kept at the same version. Never mix different versions — this is the most common source of runtime errors.

Pro Feature Overview

Feature	Core Plugin	UI Plugin	Facade Import
Pivot Table	UniverSheetsPivotTablePlugin	UniverSheetsPivotTableUIPlugin	@univerjs-pro/sheets-pivot/facade
Chart	UniverSheetsChartPlugin	UniverSheetsChartUIPlugin	@univerjs-pro/sheets-chart/facade
Sparkline	UniverSheetSparklinePlugin	UniverSheetSparklineUIPlugin	@univerjs-pro/sheets-sparkline/facade
Shape	UniverSheetsShapePlugin	UniverSheetsShapeUIPlugin	@univerjs-pro/sheets-shape/facade
Print	UniverSheetsPrintPlugin	—	@univerjs-pro/sheets-print/facade
Exchange (import/export)	UniverExchangeClientPlugin	UniverSheetsExchangeClientPlugin	@univerjs-pro/exchange-client/facade
Collaboration	UniverCollaborationPlugin + UniverCollaborationClientPlugin	UniverCollaborationClientUIPlugin	@univerjs-pro/collaboration-client/facade
Live Share	UniverLiveSharePlugin	—	@univerjs-pro/live-share/facade
License	UniverLicensePlugin	—	—

Common Tasks

Import XLSX

const unitId = await univerAPI.importXLSXToUnitIdAsync(file);
// file can be a File object or a URL string

Export XLSX

import { downloadFile } from '@univerjs-pro/exchange-client';

const fWorkbook = univerAPI.getActiveWorkbook();
const file = await univerAPI.exportXLSXByUnitIdAsync(fWorkbook.getId());
downloadFile(file, 'export', 'xlsx');

Print

const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.updatePrintConfig({
  area: univerAPI.Enum.PrintArea.CurrentSheet,
  paperSize: univerAPI.Enum.PrintPaperSize.A4,
  scale: univerAPI.Enum.PrintScale.FitPage,
});
fWorkbook.updatePrintRenderConfig({ gridlines: true });
fWorkbook.print();

Insert Chart

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
const chartInfo = fWorksheet.newChart()
  .setChartType(univerAPI.Enum.ChartType.Column)
  .addRange('A1:D6')
  .setPosition(1, 1, 0, 0)
  .build();
await fWorksheet.insertChart(chartInfo);

Insert Shape

const shapeInfo = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setPosition(1, 1, 0, 0)
  .setWidth(200)
  .setHeight(200)
  .build();
await fWorksheet.insertShape(shapeInfo);

References

• Pro features guide: references/pro-features-guide.md — complete Pro plugin registry, worker configuration, and feature matrix
• Collaboration guide: references/collaboration-guide.md — real-time collaboration setup, socket service, loading server units, status monitoring
• Exchange guide: references/exchange-guide.md — XLSX/DOCX import-export, server URLs, snapshot conversion, download utilities
• Print guide: references/print-guide.md — print configuration, preview dialog, screenshot to clipboard, events
• License guide: references/license-guide.md — license acquisition, client/server configuration, evaluation limits, verification
• Facade extension (Pro): references/facade-extension-pro.md — Pro-specific Facade methods on FUniver, FWorkbook, FWorksheet, FCollaboration