Univer Pro Integrate

Univer Pro Integrate

Add licensed Univer Pro capabilities to an existing Univer application.

Source baseline: Univer and Univer Pro 1.0.0-beta.0, synchronized with the current dream-num/univer and dream-num/univer-pro sources. Inspect the target project's installed versions first and preserve that exact release line.

Prerequisite: Use univer-integrate for the base application, container, locale, unit creation, and ordinary Facade patterns. Use univer-customize-theme for application palettes, dark mode, and the separate Pro Chart theme registry.

Choose the integration path

• Use @univerjs/preset-sheets-advanced for ordinary Pro Sheets integration. It composes the license, Pro formula, pivot table, print, chart, outline, shape, sparkline, and Sheets exchange plugins plus their Facade extensions.
• Add @univerjs/preset-sheets-collaboration for collaboration and edit history. Register it after the Advanced preset.
• Use @univerjs/preset-docs-advanced and @univerjs/preset-docs-collaboration for ordinary Pro Docs integration.
• Use Plugin Mode only for custom loading, exact bundle composition, or hosts without a matching Pro preset, such as Slides, Bases, Boards, and PDFs.
• Never register both a preset and a plugin already owned by that preset.

In 1.0.0-beta.0, Slides, Bases, Boards, and PDFs are real Pro product hosts with their own runtime/UI packages, host /facade entry, and creation method (createPresentation, createBase, createBoard, and createPdf). They do not have unified Pro presets. Follow the product matrix and Plugin Mode chains in references/pro-features-guide.md; do not infer a preset merely because a product or Facade exists.

Version policy

1. Read package.json, the lockfile, or an installed Univer package manifest.
2. Keep every @univerjs/*, @univerjs-pro/*, and @univerjs/preset-* package on the same exact Univer version.
3. For a new project targeting this source baseline, use 1.0.0-beta.0.
4. Treat a package-version mismatch as an integration error; Univer validates plugin versions at runtime.

Quick start: add Pro Sheets to the base preset

Install the Pro preset at the same version as the base preset:

bashCopy code
npm install @univerjs/preset-sheets-advanced@1.0.0-beta.0

Extend the univer-integrate Sheets preset example with the Advanced locale, stylesheet, and preset:

tsCopy code
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced';
import UniverPresetSheetsAdvancedEnUS from '@univerjs/preset-sheets-advanced/locales/en-US';

import '@univerjs/preset-sheets-advanced/lib/index.css';

declare const clientLicense: string;

const { univer, univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsAdvancedEnUS,
    ),
  },
  theme: defaultTheme,
  presets: [
    UniverSheetsCorePreset({ container: 'app' }),
    UniverSheetsAdvancedPreset({
      license: clientLicense,
      universerEndpoint: 'https://your-universer.example.com',
    }),
  ],
});

Keep the license outside source control. universerEndpoint is the Universer origin; the preset derives the upload, import, export, task, sign, and download routes from it.

Add collaboration

bashCopy code
npm install @univerjs/preset-sheets-collaboration@1.0.0-beta.0

tsCopy code
import { UniverSheetsCollaborationPreset } from '@univerjs/preset-sheets-collaboration';
import UniverPresetSheetsCollaborationEnUS from '@univerjs/preset-sheets-collaboration/locales/en-US';

import '@univerjs/preset-sheets-collaboration/lib/index.css';

const collaborationPreset = UniverSheetsCollaborationPreset({
  universerEndpoint: 'https://your-universer.example.com',
  univerContainerId: 'app',
  enableOfflineEditing: true,
});

Set collaboration: true in the top-level createUniver options, merge the collaboration locale, and append collaborationPreset after UniverSheetsAdvancedPreset(...). Pass collaboration: true to OSS feature presets that expose that option, such as the Drawing preset. Load a shared server unit with univerAPI.loadServerUnit(unitId, type) rather than creating a blank local workbook with the same ID.

Plugin Mode rules

Register a configured license before every Pro plugin:

tsCopy code
import { UniverLicensePlugin } from '@univerjs-pro/license';
import { UniverSheetsPrintPlugin } from '@univerjs-pro/sheets-print';

import '@univerjs-pro/sheets-print/facade';

univer.registerPlugin(UniverLicensePlugin, { license: clientLicense });
univer.registerPlugin(UniverSheetsPrintPlugin);

Many Pro plugins declare UniverLicensePlugin as a dependency. If a dependent plugin runs first, Univer can auto-register the license plugin with default empty configuration; a later explicit registration is then a duplicate. Configure dependencies before dependents, register all plugins before creating units, and import each required /facade side-effect entry before calling its Facade methods.

Plugin registration, Facade side-effect imports, CSS, and locales are independent requirements. In particular, importing @univerjs-pro/<package>/facade does not register its plugin or load its stylesheet. Import each selected CSS-owning package's /lib/index.css in Plugin Mode; a preset integration instead imports that preset's aggregate /lib/index.css.

Current Facade examples

Import and export Sheets:

tsCopy code
const unitId = await univerAPI.importSheetToUnitIdAsync(file);
if (!unitId) throw new Error('The workbook could not be imported');

const exported = await univerAPI.exportSheetByUnitIdAsync(unitId);
if (!exported) throw new Error('The workbook could not be exported');

univerAPI.downloadFile(exported, 'report', 'xlsx');

Print the active workbook:

tsCopy code
const workbook = univerAPI.getActiveWorkbook();
if (!workbook) throw new Error('No active workbook');

workbook.openPrintDialog();

Insert a chart:

tsCopy code
const worksheet = workbook.getActiveSheet();
if (!worksheet) throw new Error('No active worksheet');

const chartInfo = worksheet
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource({
    range: 'A1:D8',
    orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
  })
  .setPosition('F2')
  .setSize(640, 360)
  .setTitle('Quarterly sales')
  .build();

await worksheet.insertChart(chartInfo);

Feature routing

• Read references/pro-features-guide.md for presets, worker composition, and the current package families.
• Read references/collaboration-guide.md for server routes, loading shared units, status, collaborators, and flushing pending changes.
• Read references/exchange-guide.md for Sheets, Docs, Slides, Bases, Boards, and PDFs exchange methods and snapshot conversion.
• Read references/print-guide.md for Sheets print configuration, range screenshots, and Slides print.
• Read references/license-guide.md for registration order and worker-license propagation.
• Read references/facade-extension-pro.md for current pivot, chart, shape, sparkline, and collaboration Facade methods.

Anti-patterns

• Do not migrate a 0.25.0 entry by changing only version strings. Current presets, aggregate CSS, Facade export surfaces, product hosts, and registration composition differ; use the verified comparison in pro-features-guide.md.
• Do not copy 0.x method names such as importXLSXToUnitIdAsync, newChart() without a type, setChartType, newShape, or PrintOrientation into a 1.0.0-beta.0 project.
• Do not put Sheets-specific exchange options on UniverExchangeClientPlugin; configure UniverSheetsExchangeClientPlugin instead.
• Do not instantiate or mutate internal models for an operation that has a Facade or Command API.
• Do not commit client licenses or embed server-license files in frontend bundles.
• Do not omit Pro locale bundles or package styles in browser integrations.