# docx-rs

**Repository Path**: mirrors_bokuweb/docx-rs

## Basic Information

- **Project Name**: docx-rs
- **Description**: :memo:  A .docx file writer with Rust/WebAssembly.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-08
- **Last Updated**: 2026-10-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img src="https://github.com/bokuweb/docx-rs/blob/main/logo.png?raw=true" alt="docx-rs" />
</p>

<p align="center">
  Read and write .docx files with Rust, WebAssembly, and JavaScript.
</p>

---

[![GitHub Actions Status](https://github.com/bokuweb/docx-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/bokuweb/docx-rs/actions/workflows/ci.yml)
[![docx-rs at crates.io](https://img.shields.io/crates/v/docx-rs.svg)](https://crates.io/crates/docx-rs)
[![docx-rs documentation](https://docs.rs/docx-rs/badge.svg)](https://docs.rs/docx-rs)
[![docx-wasm at npm](https://img.shields.io/npm/v/docx-wasm.svg)](https://www.npmjs.com/package/docx-wasm)
[![docx-wasm downloads](https://img.shields.io/npm/dm/docx-wasm.svg)](https://www.npmjs.com/package/docx-wasm)

## Installation

### Rust

```toml
[dependencies]
docx-rs = "0.4"
```

### Browser/Node.js

```sh
pnpm add docx-wasm
```

The browser example below also uses `file-saver`.

```sh
pnpm add file-saver
```

## Usage

### Write a document with Rust

`Docx::pack` writes the package directly to the output file. Use
`Docx::build().pack(...)` only when you need access to the rendered XML package
before it is archived.

```rust
use docx_rs::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let file = std::fs::File::create("./hello.docx")?;

    Docx::new()
        .add_paragraph(Paragraph::new().add_run(Run::new().add_text("Hello")))
        .pack(file)?;

    Ok(())
}
```

### Read a document with Rust

`read_docx` parses a DOCX package into the same `Docx` model used by the writer.
The model can also be serialized to JSON. Packages whose ASCII ZIP part names
conflict with their resolved filenames are rejected.

```rust
use docx_rs::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let bytes = std::fs::read("./hello.docx")?;
    let docx = read_docx(&bytes)?;

    println!("{}", docx.json());
    Ok(())
}
```

Image previews are generated by default. If you only need the original embedded
image bytes, disable preview generation to avoid decoding and re-encoding them:

```rust
let docx = read_docx_with_options(
    &bytes,
    ReadDocxOptions::default().with_image_previews(false),
)?;
```

### Write a document in the browser

```javascript
import { saveAs } from "file-saver";

import("docx-wasm").then((w) => {
  const buffer = new w.Docx()
    .addParagraph(
      new w.Paragraph().addRun(new w.Run().addText("Hello world!"))
    )
    .build();

  saveAs(new Blob([buffer]), "hello.docx");
});
```

### Write a document with Node.js

```javascript
const w = require("docx-wasm");
const { writeFileSync } = require("fs");

const buffer = new w.Docx()
  .addParagraph(new w.Paragraph().addRun(new w.Run().addText("Hello world!")))
  .build();

writeFileSync("hello.docx", Buffer.from(buffer));
```

### Read a document with JavaScript

```javascript
const { readFileSync } = require("fs");
const { readDocx } = require("docx-wasm");

const document = readDocx(readFileSync("./hello.docx"));
console.log(document);
```

## Supported capabilities

The Rust API supports both document generation and parsing, including:

- Paragraphs, runs, text formatting, borders, tabs, and breaks
- Tables, nested tables, numbering, styles, and theme colors
- Inline and floating images
- Headers, footers, page settings, and sections
- Hyperlinks, bookmarks, comments, footnotes, and tracked changes
- Tables of contents, structured data tags, custom properties, and custom XML

The WebAssembly package exposes document generation and DOCX-to-JSON parsing for
browser and Node.js applications. OOXML is a large specification, so support is
not exhaustive.

See the [Rust API documentation](https://docs.rs/docx-rs) and
[examples directory](https://github.com/bokuweb/docx-rs/tree/main/docx-core/examples)
for the full API and focused examples.

## Development

### Requirements

- Rust 1.88 (see [`rust-toolchain`](./rust-toolchain))
- Node.js and Corepack
- pnpm 9.6.0
- [wasm-pack 0.13.1](https://rustwasm.github.io/wasm-pack/)
- [cargo-insta](https://insta.rs/docs/cli/) for reviewing Rust snapshots

### Run a Rust example

Run examples from the workspace root:

```sh
cargo run -p docx-rs --example hello
```

The `hello` example writes `output/examples/hello.docx`.

### Testing

Run the Rust test suite and lints from the workspace root:

```sh
make test
make lint
```

Review changed Rust snapshots with:

```sh
cargo insta review
```

Run the WebAssembly/JavaScript tests with:

```sh
corepack enable
cd docx-wasm
pnpm install --frozen-lockfile
pnpm test
```

Update Jest snapshots when an intentional output change requires it:

```sh
pnpm test -- --updateSnapshot
```

See [CONTRIBUTING.md](./CONTRIBUTING.md) for the pull request workflow.

## License

[MIT](./LICENSE)