Using Univer Plugins

For those who are new to Univer, the plugin-based design may bring the following confusion:

• How to know if a plugin contains a language pack?
• How to ensure the correct loading order of plugin style files?
• How to know if a plugin contains a language pack?

These questions may not have simple answers, so we provide some build tool plugins that are the best practices to solve the above problems. These plugins will automatically import style files on demand, generate language packs, etc., so you no longer need to worry about these problems.

We provide build tool plugins that support the following build tools, and you can choose the appropriate plugin according to your build tool.

Vite Plugin

Installation

pnpm add @univerjs/vite-plugin -D

Usage

Add the plugin to your vite.config.ts:

import { defineConfig } from 'vite'
import { univerPlugin } from '@univerjs/vite-plugin'
 
export default defineConfig({
  plugins: [
    univerPlugin()
  ]
})

Features

Automatic Import of Required CSS

This feature is enabled by default. You can disable it by passing css: false to the plugin options.

export default defineConfig({
  plugins: [
    univerPlugin({
+      css: false
    })
  ]
})

Simplified Import of Language Packs

The plugin provides a virtual module univer:locales, which simplifies the import of language packs.

import { LocaleType } from '@univerjs/core'
 
import { zhCN, enUS } from 'univer:locales'
 
new Univer({
  locales: {
    [LocaleType.ZH_CN]: zhCN,
    [LocaleType.EN_US]: enUS
  }
})

TypeScript Support

In order for TypeScript to recognize the univer:locales import, you should add a reference to the src/vite-env.d.ts file in your project.

/// <reference types="vite/client" />
+ /// <reference types="@univerjs/vite-plugin/types" />

Options

• css: boolean - Whether to automatically import required CSS. Default is true.

ESbuild Plugin

Installation

pnpm add @univerjs/esbuild-plugin -D

Usage

If you are using the esbuild API, you can add the plugin to your build configuration:

import esbuild from 'esbuild'
 
esbuild.build({
  plugins: [
    univerPlugin()
  ],
})

Features

Automatic Import of Required CSS

This feature is enabled by default. You can disable it by passing css: false to the plugin options.

esbuild.build({
  plugins: [
    univerPlugin({
+     css: false
    })
  ],
})

Simplified Import of Language Packs

The plugin provides a virtual module univer:locales, which simplifies the import of language packs.

import { LocaleType } from '@univerjs/core'
 
import { zhCN, enUS } from 'univer:locales'
 
new Univer({
  locales: {
    [LocaleType.ZH_CN]: zhCN,
    [LocaleType.EN_US]: enUS
  }
})

TypeScript Support

In order for TypeScript to recognize the univer:locales import, you should add a reference to the tsconfig.json file in your project.

{
  "compilerOptions": {
+    "types": ["@univerjs/esbuild-plugin/types"]
  }
}

Options

• css: boolean - Whether to automatically import required CSS. Default is true.

Webpack Plugin

Installation

pnpm add @univerjs/webpack-plugin -D

Usage

Add the plugin to your webpack.config.js:

import { UniverPlugin } from '@univerjs/webpack-plugin'
 
export default {
  plugins: [
+    new UniverPlugin()
  ]
}

Features

Automatic Import of Required CSS

This feature is enabled by default. You can disable it by passing css: false to the plugin options.

export default defineConfig({
  plugins: [
    new UniverPlugin({
+      css: false
    })
  ]
})

Simplified Import of Language Packs

The plugin provides a virtual module univer:locales, which simplifies the import of language packs.

import { LocaleType } from '@univerjs/core'
 
import { zhCN, enUS } from 'univer:locales'
 
new Univer({
  locales: {
    [LocaleType.ZH_CN]: zhCN,
    [LocaleType.EN_US]: enUS
  }
})

TypeScript Support

In order for TypeScript to recognize the univer:locales import, you should add a reference to the src/webpack-env.d.ts file in your project.

+ /// <reference types="@univerjs/webpack-plugin/types" />

Options

• css: boolean - Whether to automatically import required CSS. Default is true.