> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

## Install

In Node, `@reductoai/docx` needs Node.js 20.11 or newer.

```sh theme={null}
npm install @reductoai/docx
```

For the editor UI, also install the editor package:

```sh theme={null}
npm install @reductoai/docx-editor
```

For a read-only canvas viewer, install the viewer package:

```sh theme={null}
npm install @reductoai/viewer
```

> [!NOTE]
>
> Install these packages with an install token from the Office SDK page in [Studio](https://studio.reducto.ai/office-sdk). Studio gives you the two `.npmrc` lines:
>
> ```ini theme={null}
> @reductoai:registry=https://npm.reducto.ai/
> //npm.reducto.ai/:_authToken=${NPM_TOKEN}
> ```

## Layout engine (Node)

Your package manager installs one native engine package for your platform as an optional dependency, e.g. `@reductoai/docx-engine-linux-x64-gnu`. npm, pnpm (also with `hoist=false`), Yarn (Plug'n'Play and `node-modules`), Bun and Deno (`npm:` specifiers) install and load it.

The Linux packages need glibc 2.17 or newer. Node.js itself needs a newer glibc, so they load on the AWS Lambda Node.js runtimes (Amazon Linux 2023), Debian 11, RHEL 8 and Ubuntu 20.04.

Without a native engine, the library lays out with the bundled `engine.wasm`: the same engine as WebAssembly, slower.

| Case | Result |
| - | - |
| No engine package for the platform (musl, such as Alpine) | `engine.wasm` |
| The install skipped optional dependencies (`npm install --omit=optional`, `pnpm install --no-optional`, `bun install --omit optional`) | `engine.wasm` |
| The engine package fails to load | `engine.wasm`, and one warning |
| The engine package is from another `@reductoai/docx` version (a stale lockfile or `node_modules`) | `engine.wasm`, and one warning. Reinstall `@reductoai/docx` so the two match |
| The engine that `DOCX_ENGINE_NAPI` names fails to load | Throws |
| That engine, or `engine.wasm`, is from another version | Throws `the engine ... does not match @reductoai/docx <version>`. Reinstall, or rebuild the engine you named |

The native engine loads in `worker_threads`: workers can start, convert and exit one after another or side by side in one process.

## Optional native modules (Node)

The Node build uses native modules where they are faster. They are optional; the library uses a slower fallback when a module is missing.

| Module | Used for |
| - | - |
| `sharp` | Image decode, crops and picture effects (a dependency; without its native build, pictures count as opaque over text in extraction) |
| `@resvg/resvg-js` | EMF, WMF and SVG pictures (optional peer) |
| `skia-canvas` | PNG export (optional peer) |

## Bundlers

* The package has a `browser` export condition. Vite, webpack and esbuild select the browser build when they bundle for a page. You need no alias or polyfill.
* Browser layout runs in `@reductoai/docx/engine.wasm`. Vite, webpack and Next.js copy the file into your build. With another bundler, such as esbuild, give its URL. See [The layout engine](https://docs.reducto.ai/office/docx/js-api/browser.md#the-layout-engine).
* Vite 7 and older build workers as `iife`, which the editor's worker does not fit: set `worker: { format: "es" }` in `vite.config`.
* Keep `@reductoai/docx/node` out of client code. In Next.js, add `@reductoai/docx` and `@reductoai/portable-fonts` to `serverExternalPackages` so the server bundle keeps native modules on disk.
* Layout is CPU work. In a page, run it in a Web Worker if the document is large. The editor does this for you (see [Editor](https://docs.reducto.ai/office/docx/ui/editor.md)).

## Smoke test

```ts theme={null}
import { WordDocument } from "@reductoai/docx/node";

const doc = await WordDocument.create();
doc.body.paragraphs.items[0].insertText("Hello, Word", "Replace");
await doc.save("hello.docx");
await doc.toPdf("hello.pdf");
```

Run it with `npx tsx smoke.ts` (or compile it first). Open `hello.pdf`.
