Skip to main content

Contributing

Prerequisites​

Setup​

git clone https://github.com/your-org/docxio.git
cd docxio
pnpm install

Development commands​

Rust​

# Type check all crates (excludes WASM/napi which need special toolchains)
cargo check --workspace --exclude docxio-wasm --exclude docxio-wasm-minimal --exclude docxio-napi

# Run all Rust tests
cargo test --workspace --exclude docxio-wasm --exclude docxio-wasm-minimal --exclude docxio-napi

# Lint with Clippy (warnings are errors)
cargo clippy --workspace --exclude docxio-wasm --exclude docxio-wasm-minimal --exclude docxio-napi -- -D warnings

# Check formatting
cargo fmt --all -- --check

# Auto-format
cargo fmt --all

TypeScript​

# Type check TypeScript packages
pnpm turbo run typecheck

# Run TypeScript tests
pnpm turbo run test

# Run tests for a specific package
cd packages/docxio && npx vitest run

WASM builds​

# Build minimal WASM (441 KB)
wasm-pack build crates/docxio-wasm-minimal --target web --release

# Build full WASM (920 KB)
wasm-pack build crates/docxio-wasm --target web --release

Benchmarks​

cargo bench -p docxio-bench

Security checks​

cargo audit
cargo deny check

Testing conventions​

  • Rust: Use insta snapshot tests for XML output. Snapshots live alongside test files.
  • TypeScript: Use vitest for unit tests in packages/docxio/src/__tests__/.
  • Run cargo insta review to approve new or changed snapshots.

Code style​

  • Rust: rustfmt.toml enforces formatting. Run cargo fmt --all before committing.
  • Rust: All types use serde(rename_all = "camelCase") for JS interop.
  • Rust: XML is generated via the quick-xml Writer API -- never string concatenation.
  • TypeScript: ESM-only ("type": "module"), .js extensions in imports, strict: true.
  • TypeScript: Lowercase JSX element names map to OOXML types (e.g., <paragraph> maps to w:p).

Project structure​

docxio/
├── crates/              # Rust workspace crates
│   ├── docxio-types/    # Shared type definitions
│   ├── docxio-ooxml/    # XML generation
│   ├── docxio-core/     # Orchestration (tree → XML → ZIP)
│   ├── docxio-wasm/     # Full WASM binding
│   ├── docxio-wasm-minimal/  # Minimal WASM binding
│   ├── docxio-napi/     # Node.js native binding
│   ├── docxio-cli/      # CLI tool
│   ├── docxio-pdf/      # PDF export (planned)
│   ├── docxio-bench/    # Benchmarks
│   └── docxio-fuzz/     # Fuzz testing
├── packages/
│   ├── docxio/          # Main TypeScript package
│   ├── @docxio/html/    # HTML/Markdown export
│   ├── @docxio/zip/     # JS ZIP assembly
│   ├── @docxio/bun/     # Bun build plugin
│   └── @docxio/node/    # Native Node.js binding
└── apps/
    └── docs/            # Docusaurus documentation site

CI pipeline​

Pull requests run:

  1. cargo check + cargo clippy + cargo fmt --check
  2. cargo test (Rust unit + snapshot tests)
  3. pnpm turbo run typecheck + pnpm turbo run test (TypeScript)
  4. cargo audit + cargo deny check (security)
  5. WASM build verification