Advanced Installation
Using Package Managers
If you are familiar with modern frontend development, using package managers to build applications containing Univer will be a good choice.
We recommend using build tools such as Vite, esbuild, or Webpack 5 that have good support for ES Modules to build Univer applications. If you are using other build tools like Webpack 4, you may require some additional configurations. For more information, please refer to Read More and the Troubleshooting.
Installation
To facilitate the deployment of Univer’s frontend, a variety of npm packages are utilized. You may install the requisite packages based on your specific requirements.
- 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
peerDependencies1. - 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=true2 to resolve dependency installation issues. - If you are using yarn, you need to manually install the missing
peerDependencies3, but don’t worry, the installation commands below already include these dependencies.
The following example will guide you through which plugins are necessary and how to install them:
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-ui @univerjs/uiUpdate
Since Univer uses a monorepo to manage its codebase, each release will update the version number of all official plugins. Therefore, when updating Univer, you should update all plugins at the same time to ensure that their version numbers are consistent.
If you are using pnpm, you can use the following command to update all plugins:
pnpm update "@univerjs/*" "@univerjs-pro/*" @latestUsage
The order of importing the style files is important. Make sure you import the CSS styles of @univerjs/design and @univerjs/ui before importing the CSS styles of other plugins.
You need to import Univer’s css files, locales, and some necessary plugins in your project:
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 { LocaleType, Tools, Univer } from "@univerjs/core";
import { defaultTheme } from "@univerjs/design";
import { UniverFormulaEnginePlugin } from "@univerjs/engine-formula";
import { UniverRenderEnginePlugin } from "@univerjs/engine-render";
import { UniverUIPlugin } from "@univerjs/ui";
import { UniverDocsPlugin } from "@univerjs/docs";
import { UniverDocsUIPlugin } from "@univerjs/docs-ui";
import { UniverSheetsPlugin } from "@univerjs/sheets";
import { UniverSheetsFormulaPlugin } from "@univerjs/sheets-formula";
import { UniverSheetsFormulaUIPlugin } from "@univerjs/sheets-formula-ui";
import { UniverSheetsUIPlugin } from "@univerjs/sheets-ui";
import DesignEnUS from '@univerjs/design/locale/en-US';
import UIEnUS from '@univerjs/ui/locale/en-US';
import DocsUIEnUS from '@univerjs/docs-ui/locale/en-US';
import SheetsEnUS from '@univerjs/sheets/locale/en-US';
import SheetsUIEnUS from '@univerjs/sheets-ui/locale/en-US';
import SheetsFormulaUIEnUS from '@univerjs/sheets-formula-ui/locale/en-US';Import a variety of locales and css files for plugins may make development cumbersome and difficult to maintain. We provide Univer Plugins to help you import plugins more conveniently. For more information, please refer to the Simplified Import section.
Then create a Univer instance and register these plugins:
const univer = new Univer({
theme: defaultTheme,
locale: LocaleType.EN_US,
locales: {
[LocaleType.EN_US]: Tools.deepMerge(
SheetsEnUS,
DocsUIEnUS,
SheetsUIEnUS,
SheetsFormulaUIEnUS,
UIEnUS,
DesignEnUS,
),
},
});
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.createUnit(UniverInstanceType.UNIVER_SHEET, {});Lazy Loading
One of the advantages of using the advanced import method is that you can more flexibly control when the plugins are loaded. A common way is to load only the necessary plugins during application initialization, and delay the loading of some plugins until after the first rendering is completed.
The official demo of Univer uses this optimization technique, which you can refer to.
Using CDN
Starting from version 0.5.0, we will no longer provide UMD versions of the advanced installation method. Please use the UMD versions of the Presets installation method, or install using package management tools.