🎉 v0.5.4 is released. Read more →
GuidesUniver DocsGetting StartedInstallation & Basic Usage

Installation & Basic Usage

Univer is designed with a plugin system, we provide a rich set of plugins to help you build your own electronic document application more flexibly. You can selectively manually combine and import these plugins according to your own needs.

Since version 0.5.0, Univer provides the @univerjs/presets package, which can help you quickly build a Univer application without having to worry about the plugin design and how to import and configure those cumbersome plugins. Therefore, if you are a first-time developer using Univer, we recommend starting with Presets.

⚠️

It should be noted that whether you use the Presets package or manually combine the installation, you must ensure that all preset or plugin versions are consistent.

This chapter will guide you on how to build a basic Univer Docs application using the Univer Presets package or by piecemeal installation.

Using with Presets

Univer Presets provides a series of plugin combinations based on the functional scenarios of electronic documents, so that you can quickly build a Univer application. A preset typically includes plugins, style files, language packs, Facade API, etc.

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

Using with Package Manager

If you have already introduced modern front-end development tools into your project, introducing Univer will be very simple. We recommend using Vite, esbuild, or Webpack 5 and other build tools that support ES Module well to build Univer applications. If you are using other build tools (such as Webpack 4), you may need some additional configuration, please read Troubleshooting for more information.

Installation

Choose your package manager to install @unvierjs/presets:

npm install @univerjs/presets

Usage

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

⚠️

If your build tool does not support the exports field in package.json (common in Webpack 4), you need to manually modify the mapped path to the actual path.

import { createUniver, defaultTheme, LocaleType, merge } from '@univerjs/presets';
import { UniverDocsCorePreset } from '@univerjs/presets/preset-docs-core';
import UniverPresetDocsCoreEnUS from '@univerjs/presets/preset-docs-core/locales/en-US';
 
const { univer, univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: merge(
      {},
      UniverPresetDocsCoreEnUS,
    ),
  },
  theme: defaultTheme,
  presets: [
    UniverDocsCorePreset({
      container: 'app',
    }),
  ],
});
 
univerAPI.createUniverDoc({});
createUniver Method

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

The 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: Theme, a theme object.
  • 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 have implemented a plugin yourself, you can register these plugins through the plugins property. You can also choose to register plugins by calling the univer.registerPlugin method after obtaining the Univer instance.

Using with <script> Tag

If you are not using a package manager, you can also include Univer via the <script> tag.

We provide UMD builds of Univer on popular CDN services (such as jsDelivr, unpkg), you can include these resources in your HTML file (of course, you can also download these files and distribute them through your own server or CDN network):

Example

<head>
  <script src="https://unpkg.com/react@18.3.1/umd/react.production.min.js"></script>
  <script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.production.min.js"></script>
  <script src="https://unpkg.com/rxjs/dist/bundles/rxjs.umd.min.js"></script>
 
  <script src="https://unpkg.com/@univerjs/presets/lib/umd/index.js"></script>
  
  <script src="https://unpkg.com/@univerjs/preset-docs-core/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/preset-docs-core/lib/umd/locales/en-US.js"></script>
  <link rel="stylesheet" href="https://unpkg.com/@univerjs/preset-docs-core/lib/index.css" />
  <style>
    html,
    body,
    #root,
    #app {
      padding: 0;
      margin: 0;
      height: 100%;
    }
  </style>
</head>
<body>
  <div id="app"></div>
 
  <script>
    const { createUniver } = UniverPresets;
    const { LocaleType, merge } = UniverCore;
    const { defaultTheme } = UniverDesign;
    const { UniverDocsCorePreset } = UniverPresetDocsCore
 
    const { univerAPI } = createUniver({
      locale: LocaleType.EN_US,
      locales: {
        [LocaleType.EN_US]: merge(
          {},
          UniverPresetDocsCoreEnUS,
        ),
      },
      theme: defaultTheme,
      presets: [
        UniverDocsCorePreset(),
      ],
    });
 
    univerAPI.createUniverDoc({}); // Create your first document
  </script>
</body>

univerAPI is the API object that you can use to interact with Univer.

Specifying Versions

Both unpkg and jsDeliver support specifying resources of specific versions. For example, if you want to use version 0.5.0 of Univer, you only need to add @<version> to the URL to specify the version:

- https://unpkg.com/@univerjs/presets/lib/umd/index.js
+ https://unpkg.com/@univerjs/presets@0.5.0/lib/umd/index.js

Piecemeal Installation

Univer provides a series of functions in the form of plugins. In addition to the core plugins required by some products, you can also selectively import other plugins as needed. Here we only take the most basic Univer Docs application as an example to introduce how to manually combine and install plugins.

Unlike Presets, piecemeal installation of plugins does not include Facade API by default. The parts related to Facade API in the following code examples are optional, and you can decide whether to delete them according to your needs.

Using with Package Manager

Installation

Univer uses React to develop views (of course, this does not affect your use of Univer in Vue or Angular), and uses Rxjs to process data streams. Since these two libraries are widely used in modern front-end development, we list them as peerDependencies. Different package management tools have different behaviors for peerDependencies, so you may need to pay attention to some details.

💡
  • 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=true 2 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.
npm install @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

Usage

💡

The order of importing style files is very important. Make sure you import the CSS styles of @univerjs/design and @univerjs/ui before importing the style files of other plugins.

You need to import Univer’s style files, language packs, and some necessary plugins in your project:

import { LocaleType, merge, Univer, UniverInstanceType, FUniver } 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 DesignEnUS from '@univerjs/design/locale/en-US';
import UIEnUS from '@univerjs/ui/locale/en-US';
import DocsUIEnUS from '@univerjs/docs-ui/locale/en-US';
 
// The Facade API here is optional, you can decide whether to import it according to your needs
import '@univerjs/engine-formula/facade';
import '@univerjs/ui/facade';
import '@univerjs/docs-ui/facade';
 
import "@univerjs/design/lib/index.css";
import "@univerjs/ui/lib/index.css";
import "@univerjs/docs-ui/lib/index.css";

Then create a Univer instance and register these plugins:

const univer = new Univer({
  theme: defaultTheme,
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: merge(
      {},
      DesignEnUS,
      UIEnUS,
      DocsUIEnUS,
    ),
  },
});
 
univer.registerPlugin(UniverRenderEnginePlugin);
univer.registerPlugin(UniverFormulaEnginePlugin);
 
univer.registerPlugin(UniverUIPlugin, {
  container: 'app',
});
 
univer.registerPlugin(UniverDocsPlugin);
univer.registerPlugin(UniverDocsUIPlugin);
 
univer.createUnit(UniverInstanceType.UNIVER_DOC, {});
 
const univerAPI = FUniver.newAPI(univer);

Lazy Loading Plugins

One advantage of using the piecemeal installation method is that you can more flexibly control when the plugins are loaded. A common way is to load only the necessary plugins when the application is initialized, and delay the loading of some plugins until after the first rendering is completed.

Univer’s [official demo]((https://github.com/dream-num/univer/blob/dev/examples/src/sheets/main.ts) uses this optimization technique for reference.

Using with <script> Tag

Like Presets, Univer also provides UMD packages for each plugin, but unlike Presets, you need to manually import the UMD packages for each plugin. This process is very cumbersome, and we do not recommend this method. Please consider using it only after fully understanding the plugin mechanism (such as the dependencies between plugins and the order of importing plugin style files).

Example

We provide UMD builds of Univer on current mainstream CDN service providers (such as jsDelivr, unpkg), and you can import these resources in HTML files (of course you can also download these files and distribute them through your own server or CDN network):

<head>
  <script src="https://unpkg.com/react@18.3.1/umd/react.production.min.js"></script>
  <script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.production.min.js"></script>
  <script src="https://unpkg.com/rxjs/dist/bundles/rxjs.umd.min.js"></script>
 
  <script src="https://unpkg.com/@univerjs/protocol/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/core/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/telemetry/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/rpc/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/design/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/engine-render/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/engine-numfmt/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/engine-formula/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/drawing/lib/umd/index.js"></script>
 
  <script src="https://unpkg.com/@univerjs/ui/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/docs/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/docs-ui/lib/umd/index.js"></script>
 
  <script src="https://unpkg.com/@univerjs/engine-formula/lib/umd/facade.js"></script>
  <script src="https://unpkg.com/@univerjs/ui/lib/umd/facade.js"></script>
  <script src="https://unpkg.com/@univerjs/docs-ui/lib/umd/facade.js"></script>
 
  <script src="https://unpkg.com/@univerjs/design/lib/umd/locale/en-US.js"></script>
  <script src="https://unpkg.com/@univerjs/ui/lib/umd/locale/en-US.js"></script>
  <script src="https://unpkg.com/@univerjs/docs-ui/lib/umd/locale/en-US.js"></script>
 
  <link rel="stylesheet" href="https://unpkg.com/@univerjs/design/lib/index.css" />
  <link rel="stylesheet" href="https://unpkg.com/@univerjs/ui/lib/index.css" />
  <link rel="stylesheet" href="https://unpkg.com/@univerjs/docs-ui/lib/index.css" />
 
  <style>
    html,
    body,
    #root,
    #app {
      padding: 0;
      margin: 0;
      height: 100%;
    }
  </style>
</head>
<body>
  <div id="app"></div>
 
  <script>
    const { Univer, LocaleType, merge, UniverInstanceType, FUniver } = UniverCore
    const { defaultTheme } = UniverDesign
    const { UniverRenderEnginePlugin } = UniverEngineRender
    const { UniverFormulaEnginePlugin } = UniverEngineFormula
    const { UniverUIPlugin } = UniverUi
    const { UniverDocsPlugin } = UniverDocs
    const { UniverDocsUIPlugin } = UniverDocsUi
 
    const univer = new Univer({
      theme: defaultTheme,
      locale: LocaleType.EN_US,
      locales: {
        [LocaleType.EN_US]: merge(
          {},
          UniverDesignEnUS,
          UniverUiEnUS,
          UniverDocsUiEnUS,
        ),
      },
    });
 
    univer.registerPlugin(UniverRenderEnginePlugin);
    univer.registerPlugin(UniverFormulaEnginePlugin);
 
    univer.registerPlugin(UniverUIPlugin, {
      container: 'app',
    });
 
    univer.registerPlugin(UniverDocsPlugin);
    univer.registerPlugin(UniverDocsUIPlugin);
 
    univer.createUnit(UniverInstanceType.UNIVER_DOC, {});
 
    const univerAPI = FUniver.newAPI(univer);
  </script>
</body>

Next

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

Footnotes

  1. https://blog.npmjs.org/post/110924823920/npm-weekly-5 ↩

  2. https://pnpm.io/npmrc#auto-install-peers ↩

  3. https://github.com/yarnpkg/yarn/issues/1503 ↩

QuickstartInternationalization
Was this page helpful?