README.md

A full-stack, isomorphic office SDK for building spreadsheets, documents, and presentations.

Build embeddable productivity experiences with a plugin architecture, Canvas-based rendering, a formula engine, and one Facade API that works in the browser and on Node.js.

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Español

📖 Documentation | ✨ Showcase | 📘 API Reference | 📝 Blog

✨ What is Univer?

Univer is an open-source SDK for creating office applications inside your own product. It gives you the building blocks for spreadsheet, document, and presentation experiences without forcing you into a hosted app or a fixed UI.

Use Univer when you need to:

• Embed spreadsheet or document editing into a SaaS product, internal tool, BI workflow, or AI application.
• Run workbook/document processing on the server with the same architecture used in the browser.
• Compose only the features you need through plugins or start quickly with presets.
• Extend behavior through custom plugins, commands, services, UI components, and Facade APIs.

Univer is not a spreadsheet file viewer only. It is a framework for building your own productivity surface.

🌟 Highlights

🚀 Why Univer?

• Isomorphic by design: run UI apps in browsers and headless processing in Node.js.
• Plugin-first architecture: every capability is delivered as a composable plugin, so features can be added, removed, replaced, or lazy-loaded.
• Preset mode for fast integration: use curated plugin bundles from univer-presets when you want a working app quickly.
• Plugin mode for full control: manually compose packages when you need custom loading, smaller bundles, or deep integration.
• Facade API: work with workbooks, worksheets, ranges, documents, formulas, commands, and events through a higher-level API.
• Canvas rendering engine: support large editable document surfaces with a rendering layer shared across document types.
• Extensible UI: integrate with React, Vue, Web Components, and framework-specific application shells.

⚡ Quick Start

For most applications, start with Preset Mode. Use Plugin Mode when you need to manually compose packages and control plugin registration.

pnpm add @univerjs/presets @univerjs/preset-sheets-core

import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

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

const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(UniverPresetSheetsCoreEnUS),
  },
  presets: [
    UniverSheetsCorePreset({
      container: 'app',
    }),
  ],
})

univerAPI.createWorkbook({})

pnpm add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/sheets @univerjs/sheets-formula @univerjs/sheets-formula-ui @univerjs/sheets-numfmt @univerjs/sheets-numfmt-ui @univerjs/sheets-ui @univerjs/ui

import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { FUniver } from '@univerjs/core/facade'
import DesignEnUS from '@univerjs/design/locale/en-US'
import { UniverDocsPlugin } from '@univerjs/docs'
import { UniverDocsUIPlugin } from '@univerjs/docs-ui'
import DocsUIEnUS from '@univerjs/docs-ui/locale/en-US'
import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'
import { UniverRenderEnginePlugin } from '@univerjs/engine-render'
import { UniverSheetsPlugin } from '@univerjs/sheets'
import SheetsEnUS from '@univerjs/sheets/locale/en-US'
import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula'
import { UniverSheetsFormulaUIPlugin } from '@univerjs/sheets-formula-ui'
import SheetsFormulaUIEnUS from '@univerjs/sheets-formula-ui/locale/en-US'
import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt'
import { UniverSheetsNumfmtUIPlugin } from '@univerjs/sheets-numfmt-ui'
import SheetsNumfmtUIEnUS from '@univerjs/sheets-numfmt-ui/locale/en-US'
import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui'
import SheetsUIEnUS from '@univerjs/sheets-ui/locale/en-US'
import { UniverUIPlugin } from '@univerjs/ui'
import UIEnUS from '@univerjs/ui/locale/en-US'

import '@univerjs/design/lib/index.css'
import '@univerjs/ui/lib/index.css'
import '@univerjs/docs-ui/lib/index.css'
import '@univerjs/sheets-ui/lib/index.css'
import '@univerjs/sheets-formula-ui/lib/index.css'
import '@univerjs/sheets-numfmt-ui/lib/index.css'

import '@univerjs/engine-formula/facade'
import '@univerjs/ui/facade'
import '@univerjs/docs-ui/facade'
import '@univerjs/sheets/facade'
import '@univerjs/sheets-ui/facade'
import '@univerjs/sheets-formula/facade'
import '@univerjs/sheets-numfmt/facade'

const univer = new Univer({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      DesignEnUS,
      UIEnUS,
      DocsUIEnUS,
      SheetsEnUS,
      SheetsUIEnUS,
      SheetsFormulaUIEnUS,
      SheetsNumfmtUIEnUS,
    ),
  },
})

univer.registerPlugin(UniverRenderEnginePlugin)
univer.registerPlugin(UniverFormulaEnginePlugin)
univer.registerPlugin(UniverUIPlugin, { container: 'app' })
univer.registerPlugin(UniverDocsPlugin)
univer.registerPlugin(UniverDocsUIPlugin)
univer.registerPlugin(UniverSheetsPlugin)
univer.registerPlugin(UniverSheetsUIPlugin)
univer.registerPlugin(UniverSheetsFormulaPlugin)
univer.registerPlugin(UniverSheetsFormulaUIPlugin)
univer.registerPlugin(UniverSheetsNumfmtPlugin)
univer.registerPlugin(UniverSheetsNumfmtUIPlugin)

const univerAPI = FUniver.newAPI(univer)
univerAPI.createWorkbook({})

Your page needs a container:

<div id="app" style="height: 100vh"></div>

Learn more in the Installation & Basic Usage guide, the createUniver reference, and the Facade API reference.

🧩 Preset Mode vs Plugin Mode

Keep all @univerjs/* packages on the same version. If you use Univer Pro packages, keep @univerjs-pro/* versions aligned as well.

🧭 Compatibility

• Browser runtime: Univer is compiled with a Chrome 70 target and aims to work on Edge >=70, Firefox >=63, Chrome >=70, Safari >=12.0, and Electron >=5.
• Polyfills: Univer relies on Intl.Segmenter. Add a polyfill such as @formatjs/intl-segmenter if your target browser or runtime does not provide it.
• Build tools: We recommend Vite, esbuild, or Webpack 5. If your build tool does not support the exports field in package.json (common in Webpack 4), you may need extra path mapping.
• React: Univer's view layer is built on React 18, supports React 18 and 19, and provides minimal compatibility support for React 16.9+ and 17.
• Node.js runtime: Headless Univer supports Node.js >=18.17.0. Developing this monorepo requires Node.js >=22.18.

🛠️ What You Can Build

Sheets are the most mature product surface today. Docs and Slides share Univer's architecture and continue to evolve in the same SDK.

🔓 Open Source and Pro

This repository contains Univer's open-source core and first-party OSS plugins. Some enterprise features are developed as Univer Pro packages and require separate integration.

Pro features are documented in the Univer Pro guide. They are intentionally separated here so the OSS package surface is clear.

🌐 Ecosystem

• Core SDK: dream-num/univer, this monorepo.
• Presets: dream-num/univer-presets, curated plugin bundles for browser and Node.js apps.
• AI agent skills: dream-num/univer-sdk-skills, reusable instructions for AI agents working with Univer integration, Pro features, plugin development, and Node backends. See the AI Skills guide.
• Documentation: docs.univer.ai, including Sheets, Docs, Slides, recipes, and Pro guides.
• API Reference: docs.univer.ai/reference, the Facade API and generated API reference.
• Examples and showcase: Univer Showcase and this repository's examples/.
• AI-native spreadsheets: dream-num/univer-mcp, Univer Platform / MCP integration for driving Univer Sheets with natural language.

📦 Repository Guide

.
├── packages/      Core packages, engines, document types, UI plugins, and feature plugins
├── examples/      Local browser and Node.js demos used for development
├── common/        Shared internal tooling, mock data, storybook, and utilities
├── e2e/           Playwright and visual comparison tests
├── tests/         Additional integration test projects
└── docs/          Architecture notes, images, and repository-local documentation

Package-level READMEs live beside each package under packages/.

🧑‍💻 Development

Requirements:

• Node.js >=22.18
• pnpm >=10

git clone https://github.com/dream-num/univer.git
cd univer
pnpm install
pnpm dev

Useful commands:

Read CONTRIBUTING.md before opening a pull request.

📝 Contributor Notes

Repository-local notes worth reading before deeper changes:

• Building Isomorphic Univer: how to split browser, Node.js, UI, and shared plugin logic.
• Contributing to Facade API: API design expectations for FUniver, FWorkbook, FRange, and related Facade classes.
• Naming Convention: file, folder, interface, plugin, command, and dependency injection token conventions.
• Fixing Memory Leaks: common leak patterns and debugging workflow for Univer instances.
• Architecture TLDRs: concise notes for formula engine, web worker, permission, selection, and ref-range behavior.

💬 Community

• Ask questions in GitHub Discussions.
• Chat with the community on Discord.
• Follow Twitter / X and YouTube.

Please read the Code of Conduct before participating.

🔒 Security

If you believe you have found a security issue, please follow the Security Policy.

❤️ Sponsors

Univer is supported by the community and sponsors. You can support the project through Open Collective.

📄 License

Copyright (c) 2021-present DreamNum Co., Ltd.

Licensed under the Apache-2.0 license.