# Installation & Basic Usage

- Human documentation: [https://docs.univer.ai/guides/pdfs/getting-started/installation](https://docs.univer.ai/guides/pdfs/getting-started/installation)

- Agent Markdown: [https://docs.univer.ai/guides/pdfs/getting-started/installation.md](https://docs.univer.ai/guides/pdfs/getting-started/installation.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [pdfs/getting-started/installation/index.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/pdfs/getting-started/installation/index.mdx)

---

Univer PDFs is a Web SDK product and does not currently provide a preset. Create PDF applications with plugin mode.

## Setting Up via Plugin Mode

### Using Package Manager

Use a build tool that supports ES Modules and the `exports` field in `package.json`.

#### Installation

Univer uses React for its UI and RxJS for data streams; it can also be embedded in Vue or Angular applications. Check that `react`, `react-dom`, and `rxjs` peer dependencies are installed. The Yarn command below includes them explicitly.

Keep all `@univerjs/*` and `@univerjs-pro/*` packages on the same version.

#### pnpm

```shell
pnpm add @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui
```

#### npm

```shell
npm install @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui
```

#### yarn

```shell
yarn add @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui react react-dom rxjs
```

#### bun

```shell
bun add @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui
```

Keep every `@univerjs/*` and `@univerjs-pro/*` package on the same version.

#### Usage

Create the container before initializing Univer and give it an explicit height:

```html
<div id="app" style="height: 600px"></div>
```

Import the facade entries used below before calling `FUniver.newAPI(univer)`. Import `@univerjs/design` CSS first, then `@univerjs/ui` CSS, and finally product CSS.

1.
   Import the shared UI styles before the PDF UI style, and merge the locale packs enabled by your application:
   
   ```ts
   import { UniverLicensePlugin } from '@univerjs-pro/license'
   import { UniverPdfsPlugin } from '@univerjs-pro/pdfs'
   import { UniverPdfsUIPlugin } from '@univerjs-pro/pdfs-ui'
   import PdfsUIEnUS from '@univerjs-pro/pdfs-ui/locale/en-US'
   import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
   import { FUniver } from '@univerjs/core/facade'
   import DesignEnUS from '@univerjs/design/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-pro/pdfs-ui/lib/index.css'
   ```

1.
   Import the PDF Facade entry. This side-effect import adds PDF methods and enums to `FUniver`:
   
   ```ts
   import '@univerjs-pro/pdfs/facade'
   ```

1.
   Create the runtime, register the explicit plugin stack, and create a PDF:
   
   ```ts
   const univer = new Univer({
     locale: LocaleType.EN_US,
     locales: {
       [LocaleType.EN_US]: mergeLocales(
         DesignEnUS,
         UIEnUS,
         PdfsUIEnUS,
       ),
     },
   })
   
   univer.registerPlugin(UniverUIPlugin, { container: 'app' })
   univer.registerPlugin(UniverLicensePlugin, {
     license: process.env.CLIENT_LICENSE_TEXT,
   })
   univer.registerPlugin(UniverPdfsPlugin)
   univer.registerPlugin(UniverPdfsUIPlugin)
   
   const univerAPI = FUniver.newAPI(univer)
   univerAPI.createPdf({ name: 'Untitled PDF' })
   ```

#### `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([
  [UniverUIPlugin, { container: 'app' }],
  [UniverLicensePlugin, {
    license: process.env.CLIENT_LICENSE_TEXT,
  }],
  UniverPdfsPlugin,
  UniverPdfsUIPlugin,
])
```

## Optional thumbnail worker

Page thumbnails can render on the main thread without extra configuration. For larger documents, provide a dedicated module worker through `thumbnailWorkerURL`.

Create a worker entry such as `pdf-thumbnail.worker.ts`:

```ts
import { startPdfPageThumbnailWorker } from '@univerjs-pro/pdfs-ui'

startPdfPageThumbnailWorker()
```

Then pass its URL when registering the PDF UI plugin:

```ts
univer.registerPlugin(UniverPdfsUIPlugin, {
  thumbnailWorkerURL: new Worker(new URL('./pdf-thumbnail.worker.ts', import.meta.url), { type: 'module' }),
})
```

The option also accepts a string URL or an existing `Worker`. If workers or `OffscreenCanvas` are unavailable, thumbnail rendering falls back to the main thread.

## Collaboration-backed editing

`@univerjs-pro/pdfs-editor` is not part of the local-only stack. Do not register it by itself: first install and register the complete `@univerjs-pro/collaboration`, `@univerjs-pro/collaboration-client`, and `@univerjs-pro/collaboration-client-ui` stack as described in [Collaboration](https://docs.univer.ai/guides/pdfs/features/collaboration.md), then install and register the PDF editor lifecycle plugin.

## Node.js usage

Node.js services can register `UniverPdfsPlugin` without browser UI packages. Add the collaboration stack described above only when the service needs to load or synchronize persisted PDF units.

## Other Releases

In addition to stable releases, Univer offers alpha / beta 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-pro/pdfs@alpha # Alpha version
npm install @univerjs-pro/pdfs@beta # Beta version
```

#### pnpm

```bash
pnpm add @univerjs-pro/pdfs@alpha # Alpha version
pnpm add @univerjs-pro/pdfs@beta # Beta version
```

#### yarn

```bash
yarn add @univerjs-pro/pdfs@alpha # Alpha version
yarn add @univerjs-pro/pdfs@beta # Beta version
```

#### bun

```bash
bun add @univerjs-pro/pdfs@alpha # Alpha version
bun add @univerjs-pro/pdfs@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

* [Quickstart](https://docs.univer.ai/guides/pdfs/getting-started/quickstart.md)
* [Facade API](https://docs.univer.ai/guides/pdfs/getting-started/facade.md)
* [License and deployment](https://docs.univer.ai/server/license.md)