Installation & Basic Usage

Univer adopts a plugin-based design philosophy, aiming to provide developers with a flexible and extensible framework for electronic document applications. Through this plugin-based design, Univer can easily integrate various functional modules to meet the needs of different users. However, the plugin-based design increases the complexity of the application, especially for developers who are new to Univer.

For this reason, Univer provides two ways to help you quickly integrate and use Univer: plugin mode and preset mode. The so-called preset is actually a combination of pre-configured plugins, so the capabilities provided by both modes are the same without complex extensions.

Differences between preset mode and plugin mode:

Setting Up via Preset Mode

Here we will briefly introduce how to quickly build a Univer Docs application with less than twenty lines of code.

Using Package Manager

If your project already uses modern front-end development tools, integrating Univer will be very simple. We recommend using build tools like Vite, esbuild, or Webpack 5 that have good support for ES Modules to build Univer applications. If you are using other build tools (such as Webpack 4), you may need some additional configuration.

Installation

Choose your package manager to install @univerjs/presets:

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

npm install @univerjs/presets @univerjs/preset-docs-core

yarn add @univerjs/presets @univerjs/preset-docs-core

bun add @univerjs/presets @univerjs/preset-docs-core

Usage

With the following code, you can start a Univer Docs application:

import { UniverDocsCorePreset } from '@univerjs/preset-docs-core'import UniverPresetDocsCoreEnUS from '@univerjs/preset-docs-core/locales/en-US'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-docs-core/lib/index.css'const { univer, univerAPI } = createUniver({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      UniverPresetDocsCoreEnUS,    ),  },  presets: [    UniverDocsCorePreset({      container: 'app',    }),  ],})univerAPI.createDocument({})

The univerAPI object returned here is called the Univer Facade API, through which you can call many features provided by Univer.

createUniver Method

The createUniver method accepts a configuration object that contains the configuration information for Univer, such as language, theme, and plugins. This method returns an object containing the Univer instance and the Univer Facade API instance.

Some properties of the configuration object are as follows:

• locale: Language environment, can be an LocaleType enumeration value.
• locales: Locales, an object, the key is the language environment, and the value is the language pack object.
• theme: A theme object, which is optional.
• presets: An array of presets that contains the presets to be registered, such as UniverDocsCorePreset.
• plugins: An array of plugins that contains the plugins that need to be registered additionally.

When you use a plugin that is not included in any preset package or you implement your own plugin, you can register these plugins through the plugins property. You can also choose to register plugins using the univer.registerPlugin method after obtaining the Univer instance.

Import from CDN

If you do not want to use a package manager or just want to quickly try out Univer's features, you can import the relevant resources of Univer via CDN. For details, please refer to Using Univer via CDN.

Setting Up via Plugin Mode

Univer provides a series of features in the form of plugins. In addition to some core plugins that are essential for the product, you can selectively introduce other plugins as needed. Here, we will take the most basic Univer Docs application as an example to introduce how to manually combine and install plugins.

Different from preset mode, plugin mode does not include Facade API by default. The examples below use the Facade API, so import the corresponding facade packages before creating the API instance.

Using Package Manager

Installation

Univer uses React for its UI and RxJS for data streams; it can also be embedded in Vue or Angular applications. Check that react, react-dom, and rxjs peer dependencies are installed. The Yarn command below includes them explicitly.

Keep all @univerjs/* and @univerjs-pro/* packages on the same version.

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

npm install @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

yarn add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui react react-dom rxjs

bun add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

Usage

Create the container before initializing Univer and give it an explicit height:

<div id="app" style="height: 600px"></div>

Import the facade entries used below before calling FUniver.newAPI(univer). Import @univerjs/design CSS first, then @univerjs/ui CSS, and finally product CSS.

1. You need to import the Univer style files, language packs, and some necessary plugins in your project:

   TypeScript

   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 { 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'

2. Import the facade packages used by the example:

   TypeScript

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

3. Then create a Univer instance and register these plugins:

   TypeScript

   const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      DesignEnUS,      UIEnUS,      DocsUIEnUS,    ),  },})univer.registerPlugin(UniverRenderEnginePlugin)univer.registerPlugin(UniverFormulaEnginePlugin)univer.registerPlugin(UniverUIPlugin, {  container: 'app',})univer.registerPlugin(UniverDocsPlugin)univer.registerPlugin(UniverDocsUIPlugin)const univerAPI = FUniver.newAPI(univer)univerAPI.createDocument({})

   Expand code

univer.registerPlugin and univer.registerPlugins Methods

univer.registerPlugin method is used to register a plugin to the Univer instance. You can call this method after creating the Univer instance to register plugins.

You can register a plugin using the univer.registerPlugin(Plugin, options) method, where Plugin is the plugin to be registered, and options are optional configuration items, as each plugin may have different configuration items.

Use univer.registerPlugins to pass an array and register multiple plugins at once. This is useful for scenarios where you need to manage plugins centrally.

univer.registerPlugins([  UniverRenderEnginePlugin,  UniverFormulaEnginePlugin,  [UniverUIPlugin, {    container: 'app',  }],  UniverDocsPlugin,  UniverDocsUIPlugin,])

Lazy Loading Plugins

A common advantage of plugin mode is that you can control the loading timing of plugins more flexibly. A common approach is to load only the essential plugins during application initialization, while deferring the loading of some plugins until after the first render is complete.

// ...const univerAPI = FUniver.newAPI(univer)univerAPI.createDocument({})import('@univerjs/watermark').then(({ UniverWatermarkPlugin }) => {  univer.registerPlugin(UniverWatermarkPlugin, {    textWatermarkSettings: {      content: 'Hello, Univer!',      fontSize: 36,    },  })})

Import from CDN

If you do not want to use a package manager or just want to quickly try out Univer's features, you can import the relevant resources of Univer via CDN. For details, please refer to Using Univer via CDN.

Other Releases

In addition to stable releases, Univer offers alpha / beta and nightly channels. These versions allow you to get early access to the newest features that have not been officially released yet. However, keep in mind that more features also mean more risks. These versions may contain bugs, incomplete functionality, or unstable features. Please avoid using these versions in production environments whenever possible.

Alpha / Beta Release

When the Univer development team completes a new feature or significant change, they may pre-release it to the alpha or beta channel. You can install the alpha / beta version of a Univer package using the following command:

pnpm add @univerjs/<package-name>@alpha # Alpha version
pnpm add @univerjs/<package-name>@beta # Beta version

npm install @univerjs/<package-name>@alpha # Alpha version
npm install @univerjs/<package-name>@beta # Beta version

yarn add @univerjs/<package-name>@alpha # Alpha version
yarn add @univerjs/<package-name>@beta # Beta version

bun add @univerjs/<package-name>@alpha # Alpha version
bun add @univerjs/<package-name>@beta # Beta version

If you encounter any issues or have any feedback while using alpha / beta versions, please report them to the Univer development team through GitHub Issues.

We welcome your feedback on these early releases.

Next Steps

• Basic Concepts - Learn about the basic concepts of Univer.
• Features - Learn about the features of Univer and how to manipulate data.