diff --git a/src/docs/guides/doc/getting-started/advanced-installation.en-US.mdx b/src/docs/guides/doc/getting-started/advanced-installation.en-US.mdx new file mode 100644 index 00000000..ff5b24b6 --- /dev/null +++ b/src/docs/guides/doc/getting-started/advanced-installation.en-US.mdx @@ -0,0 +1,274 @@ +import { Callout, Tabs } from 'nextra/components' +import ReactLive from '@/components/ReactLive' +import BadgeGroup, { UniverTypes } from '@/components/BadgeGroup' + +# 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](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 like Webpack 4, you may require some additional configurations. For more information, please refer to [Read More](/guides/quickstart#read-more) and the [Troubleshooting](/guides/sheet/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 `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], 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: + + + + ```shell + pnpm add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-numfmt @univerjs/engine-render @univerjs/ui + ``` + + + ```shell + npm install @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-numfmt @univerjs/engine-render @univerjs/ui + ``` + + + ```shell + yarn add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-numfmt @univerjs/engine-render @univerjs/ui react react-dom rxjs + ``` + + + +If you want to get a more convenient development experience in the future, we also recommend you to install `@univerjs/facade`: + + + + ```shell + pnpm add @univerjs/facade + ``` + + + ```shell + npm install @univerjs/facade + ``` + + + ```shell + npm install @univerjs/facade + ``` + + + +For more information about `@univerjs/facade`, please refer to the [Facade](/guides/doc/facade/facade) section. + +### Update + +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: + +```shell +pnpm update "@univerjs/*" "@univerjs-pro/*" @latest +``` + +### Usage + + + 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: + +```typescript +import "@univerjs/design/lib/index.css"; +import "@univerjs/ui/lib/index.css"; +import "@univerjs/docs-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 DesignEnUS from '@univerjs/design/locale/en-US'; +import DocsUIEnUS from '@univerjs/docs-ui/locale/en-US'; +import UIEnUS from '@univerjs/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](/guides/sheet/getting-started/univer-plugins) section. + + +Then create a Univer instance and register these plugins: + +```typescript +const univer = new Univer({ + theme: defaultTheme, + locale: LocaleType.EN_US, + locales: { + [LocaleType.EN_US]: Tools.deepMerge( + DesignEnUS, + DocsUIEnUS, + UIEnUS, + ), + }, +}); + +univer.registerPlugin(UniverRenderEnginePlugin); +univer.registerPlugin(UniverFormulaEnginePlugin); + +univer.registerPlugin(UniverUIPlugin, { + container: 'app', + footer: false, +}); + +univer.registerPlugin(UniverDocsPlugin); +univer.registerPlugin(UniverDocsUIPlugin, { + container: 'univerdoc', + layout: { + docContainerConfig: { + innerLeft: false, + }, + }, +}); + +univer.createUnit(UniverInstanceType.UNIVER_DOC, {}); +``` + +export const code = `const univer = new Univer({ + theme: defaultTheme, + locale: LocaleType.EN_US, + locales: { + [LocaleType.EN_US]: enUS, + }, +}); + +univer.registerPlugin(UniverRenderEnginePlugin); +univer.registerPlugin(UniverFormulaEnginePlugin); + +univer.registerPlugin(UniverUIPlugin, { + container: 'app', + footer: false, +}); + +univer.registerPlugin(UniverDocsPlugin); +univer.registerPlugin(UniverDocsUIPlugin, { + container: 'univerdoc', + layout: { + docContainerConfig: { + innerLeft: false, + }, + }, +}); + +univer.createUnit(UniverInstanceType.UNIVER_DOC, {});` + + + +## Using CDN + +If you don't want to use package managers, you can also import Univer's style files, language packs, and plugins via CDN. Univer provides a separate UMD build for each plugin. Of course, the trivial UMD packages give developers a lot of flexibility, but they also pose some new challenges: + +- How do I determine the pre-dependencies of a package? +- How do I determine the correct import order? +- How do I determine which packages provide a feature? + +If you don't have a clear understanding of Univer's plugin mechanism, these questions usually mean countless trial-and-error attempts. + +Therefore, Univer also provides a UMD build that includes all plugins. You can include this UMD build in your HTML file and access each plugin through the `window` object. + +### Example + +Current mainstream CDN service providers (such as jsDelivr and unpkg) support Univer's UMD build, and you can include these resources in your HTML file: + +```html + + + + + + +
+ + + +``` + +From the above code, it can be seen that the way to import Univer via CDN is basically the same as using package managers, except that each plugin has its own namespace. Typically, the naming convention for these namespaces is the uppercase camel case `Univer`. + +### Slim Version + +If you are already using React, ReactDOM, and RxJS in your project, you can opt for the slim version of the UMD bundle, which excludes these dependencies. + +```diff ++ ++ ++ + +- ++ + +``` + +### Specifying Versions + +Both unpkg and jsDeliver support specifying specific versions of resources. For example, if you want to use version 0.1.16 of Univer, you only need to add `@` to the URL to specify the version: + +```diff +- https://unpkg.com/@univerjs/umd/lib/univer.full.umd.js ++ https://unpkg.com/@univerjs/umd@0.1.16/lib/univer.full.umd.js +``` + +--- + +[^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 diff --git a/src/docs/guides/doc/getting-started/advanced-installation.zh-CN.mdx b/src/docs/guides/doc/getting-started/advanced-installation.zh-CN.mdx new file mode 100644 index 00000000..3b9891d1 --- /dev/null +++ b/src/docs/guides/doc/getting-started/advanced-installation.zh-CN.mdx @@ -0,0 +1,265 @@ +import { Callout, Tabs } from 'nextra/components' +import ReactLive from '@/components/ReactLive' +import BadgeGroup, { UniverTypes } from '@/components/BadgeGroup' + +# 高级安装和引入 + + + + + - 如果你正在使用 npm,请确保使用的版本为 npm@7 及以上。这是因为 npm@3 ~ npm@6 并不会正确地安装 `peerDependencies`[^1]。 + - 如果你正在使用 pnpm,请确保使用的版本为 pnpm@8 及以上。如果你正在使用 pnpm@6 ~ pnpm@7,可以尝试配置 `auto-install-peers=true` [^2]来解决依赖安装问题。 + - 如果你正在使用 yarn,你需要手动安装缺失的 `peerDependencies`[^3],不过别担心,下面的安装命令中已经包含了这些依赖。 + + +以下示例将会带你了解哪些插件是必需的,以及如何安装它们: + + + + ```shell + pnpm add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-numfmt @univerjs/engine-render @univerjs/ui + ``` + + + ```shell + npm install @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-numfmt @univerjs/engine-render @univerjs/ui + ``` + + + ```shell + yarn add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-numfmt @univerjs/engine-render @univerjs/ui react react-dom rxjs + ``` + + + +如果你想在后续的开发中获得更加便捷的开发体验,我们还推荐你安装 `@univerjs/facade`: + + + + + ```shell + pnpm add @univerjs/facade + ``` + + + ```shell + npm install @univerjs/facade + ``` + + + ```shell + npm install @univerjs/facade + ``` + + + +有关 `@univerjs/facade` 的更多信息,请参考 [Facade](/guides/doc/facade/facade) 章节。 + +### 更新 + +由于 Univer 使用了 monorepo 的方式进行管理,每次发布都会更新所有官方插件的版本号。因此在更新 Univer 时,你应当同时更新所有的插件,保证它们的版本号一致。 + +如果你使用的是 pnpm,你可以使用以下命令来更新所有的插件: + +```shell +pnpm update "@univerjs/*" "@univerjs-pro/*" @latest +``` + +### 使用 + + + 样式文件的引入顺序很重要,确保你在依次引入 `@univerjs/design`、`@univerjs/ui` 的 CSS 样式后再引入其他插件的样式文件。 + + +你需要在项目中引入 Univer 的样式文件、语言包,以及一些必要的插件: + +```typescript +import "@univerjs/design/lib/index.css"; +import "@univerjs/ui/lib/index.css"; +import "@univerjs/docs-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 DesignZhCN from '@univerjs/design/locale/zh-CN'; +import DocsUIZhCN from '@univerjs/docs-ui/locale/zh-CN'; +import UIZhCN from '@univerjs/ui/locale/zh-CN'; +``` + + + 大量插件的语言包和样式加载可能会使开发变得繁琐且难以维护。我们提供了 Univer Plugins 来帮助你更加方便地引入插件,详情请参考 [简化引入](/guides/sheet/getting-started/univer-plugins) 章节。 + + +然后创建一个 Univer 实例,并注册这些插件: + +```typescript +const univer = new Univer({ + theme: defaultTheme, + locale: LocaleType.ZH_CN, + locales: { + [LocaleType.ZH_CN]: Tools.deepMerge( + DesignZhCN, + DocsUIZhCN, + UIZhCN, + ), + }, +}); + +univer.registerPlugin(UniverRenderEnginePlugin); +univer.registerPlugin(UniverFormulaEnginePlugin); + +univer.registerPlugin(UniverUIPlugin, { + container: 'app', + footer: false, +}); + +univer.registerPlugin(UniverDocsPlugin); +univer.registerPlugin(UniverDocsUIPlugin, { + container: 'univerdoc', + layout: { + docContainerConfig: { + innerLeft: false, + }, + }, +}); + +univer.createUnit(UniverInstanceType.UNIVER_DOC, {}); +``` + +export const code = `const univer = new Univer({ + theme: defaultTheme, + locale: LocaleType.ZH_CN, + locales: { + [LocaleType.ZH_CN]: zhCN, + }, +}); + +univer.registerPlugin(UniverRenderEnginePlugin); +univer.registerPlugin(UniverFormulaEnginePlugin); + +univer.registerPlugin(UniverUIPlugin, { + container: 'app', + footer: false, +}); + +univer.registerPlugin(UniverDocsPlugin); +univer.registerPlugin(UniverDocsUIPlugin, { + container: 'univerdoc', + layout: { + docContainerConfig: { + innerLeft: false, + }, + }, +}); + +univer.createUnit(UniverInstanceType.UNIVER_DOC, {});` + + + +## 通过 CDN 引入 + +如果你不想使用包管理工具,你也可以通过 CDN 引入 Univer 的样式文件、语言包和插件。Univer 为每一个插件都提供了单独的 UMD 构建。当然,琐碎的 UMD 包会使得开发者拥有非常灵活的选择权,但也同样会让开发者面临一些新的挑战: + +- 我要如何确定一个包的前置依赖? +- 我要如何确定正确的引入顺序? +- 我要如何确定一个功能究竟是由哪些包提供的? + +如果对 Univer 的插件化机制没有一个非常清晰的了解的话,通常来说这些问题的背后就意味着无数种排列组合尝试的过程。 + +因此,Univer 也提供了一个包含了所有插件的 UMD 构建,你可以在 HTML 文件中引入这个 UMD 构建,然后通过 `window` 对象来访问各个插件。 + +### 示例 + +当前主流的 CDN 服务商(例如 jsDelivr、unpkg)都支持 Univer 的 UMD 构建,你可以在 HTML 文件中引入这些资源: + +```html + + + + + + +
+ + + +``` + +从上面的代码可以看出,通过 CDN 引入 Univer 的方式和使用包管理工具引入的方式基本一致,只是每个插件都有属于自己的命名空间。通常这些命名空间的命名规则为大写驼峰的 `Univer`。 + +### 精简版本 + +如果你的项目中已经使用了 React、ReactDOM 和 RxJS,你可以选择 UMD 包的精简版本,该版本不包含这些依赖项。 + +```diff ++ ++ ++ + +- ++ + +``` + +### 指定版本 + +unpkg 和 jsDeliver 都支持指定特定版本的资源。以 unpkg 为例,如果你想使用 0.1.16 版本的 Univer,仅需在 URL 中加上 `@` 来指定版本即可: + +```diff +- https://unpkg.com/@univerjs/umd/lib/univer.full.umd.js ++ https://unpkg.com/@univerjs/umd@0.1.16/lib/univer.full.umd.js +``` + +--- + +[^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 diff --git a/src/docs/guides/doc/getting-started/installation.en-US.mdx b/src/docs/guides/doc/getting-started/installation.en-US.mdx index 4b442fde..e8eb955c 100644 --- a/src/docs/guides/doc/getting-started/installation.en-US.mdx +++ b/src/docs/guides/doc/getting-started/installation.en-US.mdx @@ -6,6 +6,12 @@ import BadgeGroup, { UniverTypes } from '@/components/BadgeGroup' +From version 0.5.0, Univer provides the `@univerjs/presets` package, which provides presets for common scenarios to help you quickly build a Univer application without worrying about how to import and configure Univer plugins. + + + If you are using Univer for the first time, we recommend starting with Presets. In the following sections, unless otherwise specified, we will assume that you are using Presets. If you are already familiar with Univer and want to import plugins more flexibly (e.g., lazy loading some plugins), you can refer to the [Advanced Installation](/guides/sheet/advanced-installation) section. + + ## Using Package Managers If you are familiar with modern frontend development, using package managers to build applications containing Univer will be a good choice. @@ -14,140 +20,49 @@ We recommend using build tools such as [Vite](https://vitejs.dev/), [esbuild](ht ### 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 `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], 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: +Choose your package manager to install `@unvierjs/presets`: ```shell - pnpm add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-numfmt @univerjs/engine-render @univerjs/ui + pnpm add @univerjs/presets ``` ```shell - npm install @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-numfmt @univerjs/engine-render @univerjs/ui + npm install @univerjs/presets ``` ```shell - yarn add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-numfmt @univerjs/engine-render @univerjs/ui react react-dom rxjs + yarn add @univerjs/presets ``` -If you want to get a more convenient development experience in the future, we also recommend you to install `@univerjs/facade`: - - - - ```shell - pnpm add @univerjs/facade - ``` - - - ```shell - npm install @univerjs/facade - ``` - - - ```shell - npm install @univerjs/facade - ``` - - - -For more information about `@univerjs/facade`, please refer to the [Facade](/guides/doc/facade/facade) section. - -### Update - -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: - -```shell -pnpm update "@univerjs/*" "@univerjs-pro/*" @latest -``` - ### Usage - - 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: - ```typescript -import "@univerjs/design/lib/index.css"; -import "@univerjs/ui/lib/index.css"; -import "@univerjs/docs-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 DesignEnUS from '@univerjs/design/locale/en-US'; -import DocsUIEnUS from '@univerjs/docs-ui/locale/en-US'; -import UIEnUS from '@univerjs/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](/guides/sheet/getting-started/univer-plugins) section. - - -Then create a Univer instance and register these plugins: - -```typescript -const univer = new Univer({ - theme: defaultTheme, - locale: LocaleType.EN_US, - locales: { - [LocaleType.EN_US]: Tools.deepMerge( - DesignEnUS, - DocsUIEnUS, - UIEnUS, - ), - }, -}); - -univer.registerPlugin(UniverRenderEnginePlugin); -univer.registerPlugin(UniverFormulaEnginePlugin); - -univer.registerPlugin(UniverUIPlugin, { - container: 'app', - footer: false, -}); - -univer.registerPlugin(UniverDocsPlugin); -univer.registerPlugin(UniverDocsUIPlugin, { - container: 'univerdoc', - layout: { - docContainerConfig: { - innerLeft: false, - }, - }, +import { createUniver, defaultTheme, LocaleType } from '@univerjs/presets'; +import { zhCN } from '@univerjs/presets/docs/docs-basic/zh-CN'; +import { UniverDocsBasicPreset } from '@univerjs/presets/presets/docs/docs-basic/index.js'; + +const { univerAPI } = createUniver({ + locale: LocaleType.ZH_CN, + theme: defaultTheme, + presets: [ + UniverDocsBasicPreset({ locales: { zhCN } }), + ], }); -univer.createUnit(UniverInstanceType.UNIVER_DOC, {}); +univerAPI.createUniverDoc({}); ``` export const code = `const univer = new Univer({ theme: defaultTheme, - locale: LocaleType.EN_US, + locale: LocaleType.ZH_CN, locales: { - [LocaleType.EN_US]: enUS, + [LocaleType.ZH_CN]: zhCN, }, }); @@ -173,17 +88,19 @@ univer.createUnit(UniverInstanceType.UNIVER_DOC, {});` -## Using CDN +### Update -If you don't want to use package managers, you can also import Univer's style files, language packs, and plugins via CDN. Univer provides a separate UMD build for each plugin. Of course, the trivial UMD packages give developers a lot of flexibility, but they also pose some new challenges: +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. -- How do I determine the pre-dependencies of a package? -- How do I determine the correct import order? -- How do I determine which packages provide a feature? +If you are using pnpm, you can use the following command to update all plugins: + +```shell +pnpm update "@univerjs/presets" @latest +``` -If you don't have a clear understanding of Univer's plugin mechanism, these questions usually mean countless trial-and-error attempts. +## Import by a `