# Installation & Basic Usage - Human documentation: [https://docs.univer.ai/guides/sheets/getting-started/installation](https://docs.univer.ai/guides/sheets/getting-started/installation) - Agent Markdown: [https://docs.univer.ai/guides/sheets/getting-started/installation.md](https://docs.univer.ai/guides/sheets/getting-started/installation.md) - Requested language: `en-US` - Content language: `en-US` - Documentation version: `1.0.0-rc.0` - Source: [sheets/getting-started/installation/index.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/getting-started/installation/index.mdx) --- 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. > [!WARNING: Caution] > * **Consistent Dependency Versions**: Whether you use preset mode or plugin mode, you must ensure that all dependencies have consistent version numbers. > * **Cautious Mixing of Plugins and Presets**: If a plugin is already included in a preset, you do not need to import that plugin separately when using the preset. Otherwise, it may lead to plugin conflicts or functional anomalies. Differences between preset mode and plugin mode: | Plugin Mode | Preset Mode | | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Requires manual import of corresponding facade packages | No need to manually import any facade packages | | Requires attention to the registration order of plugins with the same functionality | No need to pay attention to the registration order of functionalities included in presets | | Supports on-demand lazy loading | Loads configured presets synchronously during initialization | Univer supports two integration modes: *Preset Mode* and *Plugin Mode*. Preset Mode simplifies setup with preconfigured plugin bundles. If you need **deep customization or extensions**, we recommend Plugin Mode so you can combine and configure plugins individually. ## 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 Sheets application as an example to introduce how to manually combine and install plugins. Different from preset mode, plugin mode does not include Facade API[^facade-entry] by default. The parts related to Facade API in the following code examples are optional, and you can decide whether to remove them based on your needs. ### Using Package Manager #### Installation We use React to develop the view (this does not affect your use of Univer in Vue or Angular), and Rxjs to handle data streams. Since these two libraries are widely used in modern front-end development, we treat them as peerDependencies[^peer-dependency]. However, different package management tools have different behaviors regarding peerDependencies, so you may need to pay attention to some details. > [!NOTE] > * If you are using npm, make sure you are using npm\@7 or higher. This is because npm\@3 \~ npm\@6 will not correctly install `peerDependencies`[^1]. > * If you are using pnpm, make sure you are using pnpm\@8 or higher. If you are using pnpm\@6 \~ pnpm\@7, you can try configuring `auto-install-peers=true` [^2] to resolve dependency installation issues. > * If you are using yarn, you need to manually install the missing `peerDependencies`[^3], the installation commands below already include these dependencies. #### pnpm ```shell 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 ``` #### npm ```shell npm install @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 ``` #### yarn ```shell yarn 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 react react-dom rxjs ``` #### bun ```shell bun 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 ``` #### Usage > [!WARNING: Caution] > * Not all plugins include facade packages, language packs, and style files. We will specify this in the documentation for each feature. > * The order of importing style files is important. Make sure to import the CSS styles of `@univerjs/design` and `@univerjs/ui` before importing the styles of other plugins. 1. You need to import the Univer style files, language packs, and some necessary plugins in your project: ```typescript import { LocaleType, mergeLocales, Univer, UniverInstanceType } 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 { 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 SheetsEnUS from '@univerjs/sheets/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' ``` 1. If you need to use the Facade API, you can import the relevant facade packages here. This is optional, but recommended: ```typescript 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' ``` 1. 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, 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) univer.createUnit(UniverInstanceType.UNIVER_SHEET, {}) const univerAPI = FUniver.newAPI(univer) ``` > Interactive example: [Open the playground](/playground/sheets/slim-via-plugin) #### `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. ```typescript univer.registerPlugins([ UniverRenderEnginePlugin, UniverFormulaEnginePlugin, [UniverUIPlugin, { container: 'app', }], UniverDocsPlugin, UniverDocsUIPlugin, UniverSheetsPlugin, UniverSheetsUIPlugin, UniverSheetsFormulaPlugin, UniverSheetsFormulaUIPlugin, UniverSheetsNumfmtPlugin, UniverSheetsNumfmtUIPlugin, ]) ``` #### 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. ```typescript // ... univer.createUnit(UniverInstanceType.UNIVER_SHEET, {}) import('@univerjs/watermark').then(({ UniverWatermarkPlugin }) => { univer.registerPlugin(UniverWatermarkPlugin, { textWatermarkSettings: { content: 'Hello, Univer!', fontSize: 36, }, }) }) ``` Our [official demo](https://github.com/dream-num/univer/blob/0d849012594882307186f33734b8b89d80a729e9/examples/src/sheets/main.ts) uses this optimization technique, which you can refer to. ### Mobile Support Univer provides **experimental** mobile support. The mobile version is optimized for touch interactions, offering UI components and interaction experiences tailored for mobile devices. * **UI plugins**: To adapt to different interaction patterns across devices, some UI plugins provide both desktop and mobile variants. These two variants live in the same npm package and are distinguished by different export paths. * **Core logic plugins**: Such as the formula engine (`UniverFormulaEnginePlugin`) and render engine (`UniverRenderEnginePlugin`), remain the same on both desktop and mobile, so there is no need to differentiate versions. > [!INFO] > Mobile and desktop plugins are not two completely separate packages—they are the same package presented differently on different platforms. For example, `@univerjs/sheets-ui` provides both the desktop `UniverSheetsUIPlugin` and the mobile `UniverSheetsMobileUIPlugin`. > [!WARNING: Notes] > * Mobile support is currently experimental, and some features may be incomplete. > * Mobile UI plugins and desktop UI plugins cannot be used at the same time; choose the appropriate plugin based on the device type. > * Thorough testing is recommended before deploying to production. > Interactive example: [Open the playground](/playground/sheets/mobile-via-plugin) #### Switch to Mobile Plugins Simply replace the corresponding UI plugin with its mobile variant: ```typescript import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui' // [!code --] import { UniverSheetsMobileUIPlugin } from '@univerjs/sheets-ui' // [!code ++] univer.registerPlugin(UniverSheetsUIPlugin) // [!code --] univer.registerPlugin(UniverSheetsMobileUIPlugin) // [!code ++] ``` #### Desktop vs. Mobile Plugin Mapping The table below lists all UI plugins that provide mobile variants. If you need to dynamically choose plugins based on device type, refer to the mapping table: | Desktop Plugin | Mobile Plugin | Package | | ------------------------------------------- | ------------------------------------------------- | -------------------------------------------- | | `UniverUIPlugin` | `UniverMobileUIPlugin` | `@univerjs/ui` | | `UniverSheetsUIPlugin` | `UniverSheetsMobileUIPlugin` | `@univerjs/sheets-ui` | | `UniverSheetsFilterUIPlugin` | `UniverSheetsFilterMobileUIPlugin` | `@univerjs/sheets-filter-ui` | | `UniverSheetsDataValidationUIPlugin` | `UniverSheetsDataValidationMobileUIPlugin` | `@univerjs/sheets-data-validation-ui` | | `UniverSheetsConditionalFormattingUIPlugin` | `UniverSheetsConditionalFormattingMobileUIPlugin` | `@univerjs/sheets-conditional-formatting-ui` | | `UniverThreadCommentUIPlugin` | `UniverThreadCommentMobileUIPlugin` | `@univerjs/thread-comment-ui` | | `UniverSheetsThreadCommentUIPlugin` | `UniverSheetsThreadCommentMobileUIPlugin` | `@univerjs/sheets-thread-comment-ui` | In subsequent feature documentation, if a feature has a mobile adaptation plugin, we will note it in the corresponding section. ### 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](https://docs.univer.ai/guides/sheets/getting-started/installation/cdn.md#plugin-mode). ## Setting Up via Preset Mode Here we will briefly introduce how to quickly build a Univer Sheets 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](https://vitejs.dev/), [esbuild](https://esbuild.github.io/), or [Webpack 5](https://webpack.js.org/) 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`: #### npm ```bash npm install @univerjs/presets @univerjs/preset-sheets-core ``` #### pnpm ```bash pnpm add @univerjs/presets @univerjs/preset-sheets-core ``` #### yarn ```bash yarn add @univerjs/presets @univerjs/preset-sheets-core ``` #### bun ```bash bun add @univerjs/presets @univerjs/preset-sheets-core ``` #### Usage > [!WARNING] > If your build tool does not support the `exports` field in package.json (common in Webpack 4), you need to manually change the mapped paths to the actual paths. With the following code, you can start a Univer Sheets application: ```html title="index.html"
``` ```typescript 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 { univer, univerAPI } = createUniver({ locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: mergeLocales( UniverPresetSheetsCoreEnUS, ), }, presets: [ UniverSheetsCorePreset({ container: 'app', }), ], }) univerAPI.createWorkbook({}) ``` The `univerAPI` object returned here is called the Univer Facade API, through which you can call many features provided by Univer. > Interactive example: [Open the playground](/playground/sheets/slim-via-preset) > [!WARNING] > You can also import `UniverSheetsCorePreset` from `@univerjs/presets/preset-sheets-core`, but you must ensure that your build tool supports the `exports` field in package.json. #### `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 `UniverSheetsCorePreset`. * `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. > [!NOTE] > You can find more detailed information about the `createUniver` method in the [API Reference / createUniver](https://docs.univer.ai/reference/methods/create-univer.md). ### 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](https://docs.univer.ai/guides/sheets/getting-started/installation/cdn.md#plugin-mode). ## 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: #### npm ```bash npm install @univerjs/@alpha # Alpha version npm install @univerjs/@beta # Beta version ``` #### pnpm ```bash pnpm add @univerjs/@alpha # Alpha version pnpm add @univerjs/@beta # Beta version ``` #### yarn ```bash yarn add @univerjs/@alpha # Alpha version yarn add @univerjs/@beta # Beta version ``` #### bun ```bash bun add @univerjs/@alpha # Alpha version bun add @univerjs/@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](https://github.com/dream-num/univer/issues). We welcome your feedback on these early releases. ## Next Steps * [Basic Concepts](https://docs.univer.ai/guides/sheets/getting-started/quickstart.md#basic-concepts) - Learn about the basic concepts of Univer. * [Features](https://docs.univer.ai/guides/sheets/features/core.md) - Learn about the features of Univer and how to manipulate data. *** [^1]: [https://blog.npmjs.org/post/110924823920/npm-weekly-5](https://blog.npmjs.org/post/110924823920/npm-weekly-5) [^2]: [https://pnpm.io/npmrc#auto-install-peers](https://pnpm.io/npmrc#auto-install-peers) [^3]: [https://github.com/yarnpkg/yarn/issues/1503](https://github.com/yarnpkg/yarn/issues/1503) [^facade-entry]: Facade is the application-facing API over registered plugins. Importing a Facade entry adds API methods; it does not register the feature plugin itself. [^peer-dependency]: `peerDependencies` declare dependencies that the host application must provide with compatible versions. They let Univer share libraries such as React instead of bundling a separate copy.