DEV Community

Cover image for WordCraft Explained: Install, Edit DOCX, and Export PDF
Faizan
Faizan

Posted on Originally published at headsntail.com

WordCraft Explained: Install, Edit DOCX, and Export PDF

#javascript #tutorial #webdev

Can an open-source application written in Rust really replace Microsoft Word, open your existing DOCX files, and run without a Microsoft 365 subscription?

WordCraft is trying to do exactly that. It's an independent, clean-room reimplementation of Microsoft Word, built around a Rust document engine with desktop, command-line, and browser interfaces.

The interesting part for developers isn't simply another word processor. WordCraft also exposes document operations through a CLI and an MCP server, making it relevant to document automation, self-hosted workflows, and AI-assisted editing.

In this tutorial, we'll install WordCraft, create a sample project report, convert it into DOCX and PDF, inspect its contents, and explore the browser version. We'll also discuss where it makes sense compared with Microsoft Word, LibreOffice, ONLYOFFICE, and existing document-generation tools.

One important qualification: WordCraft is currently an alpha project. Its developers document a substantial set of implemented features, but complex document compatibility and overall stability are still being improved.

The commands below follow the project's published documentation. They are documented usage examples, not independent benchmark results.

Official repository: storytold/wordcraft on GitHub

Step 1: Understand WordCraft Before Installing It

WordCraft is more than a basic text editor.

Its goal is to reproduce familiar Word workflows, including:

  • Ribbon-style menus and editing shortcuts.
  • Paragraph formatting, styles, and document themes.
  • Tables, lists, headers, footers, and page layouts.
  • Comments, track changes, and document review.
  • References, footnotes, citations, and tables of contents.
  • Mail merge and document templates.
  • DOCX import and export.
  • PDF generation.
  • Command-line and agent-based document operations.

The project also documents support for formats including Markdown, HTML, RTF, ODT, LaTeX, and plain text.

What does clean-room reimplementation mean?

WordCraft does not package Microsoft Word or require Microsoft's application to perform its core editing operations.

Instead, its developers describe an implementation based on publicly available specifications and observed application behavior.

That's the purpose of the term clean-room: implementing compatible functionality independently rather than copying proprietary implementation code.

It does not guarantee identical behavior, complete file compatibility, or feature parity with Microsoft Word.

That distinction matters when handling documents with complex layouts, tracked changes, embedded objects, or unusual formatting.

Why build a word processor in Rust?

Rust is useful for systems requiring careful memory management, predictable data structures, and native execution.

WordCraft divides its implementation into components responsible for different document operations.

Component Responsibility
Document model Text, formatting, paragraphs, and editing
Layout engine Line breaking, tables, and pagination
DOCX handling Reading and writing Word documents
Rendering Drawing document pages
PDF support Exporting documents
Command engine Editing operations and undo history
Desktop interface Word-style graphical editor
CLI and MCP Automation and external control

The desktop application uses egui, while the browser version uses WebAssembly.

That allows the project to share Rust-based functionality across different interfaces.

For developers, the architecture is interesting because document editing is not exclusively tied to a graphical application.

Who should consider WordCraft?

It's particularly relevant if you:

  • Want to test an independent Word-compatible editor.
  • Build systems that produce DOCX or PDF reports.
  • Need local document processing without relying on a cloud office service.
  • Work with Rust and want to explore document-engine architecture.
  • Experiment with automated document editing and AI agents.
  • Prefer open-source applications that can be inspected and modified.

For legal documents, financial reports, or customer contracts where formatting must remain identical, continue using a validated production workflow until WordCraft passes your own compatibility tests.

Step 2: Install WordCraft on Your Computer

There are two practical installation paths: download a packaged release or compile the source code.

Choose a packaged release if you simply want to try the editor.

Choose the source build if you want access to the CLI, want to inspect the implementation, or plan to contribute code.

Option A: Download a desktop release

Visit:

WordCraft GitHub Releases

The project publishes platform-specific packages, including Windows installers, macOS application images, and Linux packages.

Download the build that matches your operating system and processor architecture.

For example, a Windows user should select the appropriate Windows installer or portable archive.

Linux users can choose between the available distribution packages, AppImage, and archive formats.

Follow the release instructions and verify downloaded files against the checksums supplied with that release.

Expected result: You can launch WordCraft as a regular desktop application without building the Rust source yourself.

Option B: Build WordCraft from source

For the remaining terminal examples, we'll use Bash on Linux or macOS. Windows developers can run the equivalent Cargo commands in PowerShell.

First, confirm that Git and Rust are installed:

git --version
rustc --version
cargo --version
Enter fullscreen mode Exit fullscreen mode

Each command should report an installed version.

If Rust is missing, install it using the instructions at rustup.rs.

On Linux, native desktop builds may also require system development packages for the windowing and graphics dependencies. Check compiler errors and the project's build documentation if anything is missing.

Clone the official repository:

git clone https://github.com/storytold/wordcraft.git
cd wordcraft
Enter fullscreen mode Exit fullscreen mode

Next, build the desktop application and command-line tool:

cargo build --release -p wordcraft -p wordcraft-cli
Enter fullscreen mode Exit fullscreen mode

Cargo will download dependencies and compile the workspace packages.

The initial build may take a while, depending on your hardware and dependency cache.

Expected result: After a successful build, the release directory contains the application and CLI binaries.

On Linux or macOS, check the CLI binary:

./target/release/wordcraft-cli --help
Enter fullscreen mode Exit fullscreen mode

This should display the command-line interface's available commands and options.

On Windows PowerShell, the equivalent executable path is:

.\target\release\wordcraft-cli.exe --help
Enter fullscreen mode Exit fullscreen mode

You do not need to install Microsoft Word for these commands.

Step 3: Open the WordCraft Editor and Sample Document

Before automating documents, it's helpful to understand what the graphical editor actually provides.

WordCraft includes a sample document that demonstrates its interface and editing features.

From the repository root, launch it with:

cargo run --release -p wordcraft -- --sample
Enter fullscreen mode Exit fullscreen mode

This command builds the desktop package if necessary and starts the application with its sample document.

Expected result: A desktop window opens with a document editor featuring a ribbon-style interface, page layout, formatting controls, and the project's sample content.

You should recognize many familiar Word concepts:

  • Home controls for fonts, paragraphs, and styles.
  • Insert tools for tables and document elements.
  • Layout options for pages and margins.
  • Review tools for comments and tracked changes.
  • Document navigation and viewing controls.

Try editing a paragraph, making some text bold, changing a heading style, and inserting a table.

These basic operations establish whether the editor behaves comfortably on your system.

Open an existing Word document

If you already have a DOCX file in the current directory, launch it with:

cargo run --release -p wordcraft -- report.docx
Enter fullscreen mode Exit fullscreen mode

Replace report.docx with your actual file path.

WordCraft attempts to import the document for editing.

This is where you should start evaluating compatibility.

Check headings, tables, images, page breaks, fonts, and headers before making changes.

A DOCX file opening successfully does not necessarily mean every visual element survived the import unchanged.

For important documents, save a separate copy rather than overwriting the original.

Step 4: Create a Project Report and Convert It to DOCX

Let's use one practical example throughout the rest of the tutorial.

Imagine you maintain a PHP/Laravel application and want to generate a weekly deployment report.

Your application could produce the initial report as Markdown, then use a document tool to turn it into a format colleagues can edit.

For this demonstration, we'll create the Markdown file manually.

From the WordCraft repository root, create report.md:

cat > report.md <<'EOF'
# Weekly Deployment Report

## Project Overview

Project: Laravel Customer Portal

Status: Testing

## Completed Work

- Updated authentication screens.
- Fixed file upload validation.
- Improved application error logging.

## Pending Work

- Complete browser compatibility checks.
- Review deployment configuration.
- Prepare the production release.

## Deployment Notes

All changes must pass review before production deployment.
EOF
Enter fullscreen mode Exit fullscreen mode

The file now contains a simple structured report.

Because Markdown uses ordinary text with lightweight formatting markers, it's easy to generate from scripts, scheduled jobs, or application templates.

Convert Markdown into DOCX

Use the WordCraft CLI:

./target/release/wordcraft-cli convert report.md report.docx
Enter fullscreen mode Exit fullscreen mode

The CLI's documented conversion functionality supports Markdown and DOCX among its document formats.

Expected result: WordCraft writes a report.docx document if the conversion succeeds.

You can then open it in the graphical editor:

cargo run --release -p wordcraft -- report.docx
Enter fullscreen mode Exit fullscreen mode

Check whether the heading hierarchy, paragraphs, and bullet points appear correctly.

This is a basic example, not a promise that every Markdown extension, custom HTML block, or advanced formatting feature will convert perfectly.

Why this workflow matters

For a Laravel application, Markdown can act as an intermediate document format.

For example:

  1. Laravel collects report data.
  2. A template generates Markdown.
  3. A background job invokes an approved document-conversion process.
  4. The generated DOCX becomes available for download.
  5. Users open and edit the document with their preferred office software.

WordCraft potentially fits into the conversion step.

However, don't assume its CLI is already production-ready for every server configuration. Test file fidelity, error handling, process permissions, and resource usage first.

If the report is downloaded through a PHP application, also ensure your upload and request-body configuration is appropriate. Our guide to fixing PHP POST request capacity errors covers the limits that can affect file-based workflows.

Step 5: Inspect the DOCX and Export a PDF

Creating a DOCX is useful, but many developer workflows also require PDF output.

For example, your Laravel portal might allow staff to edit a Word report and then publish a PDF copy for distribution.

WordCraft provides a CLI conversion command for this.

Run:

./target/release/wordcraft-cli convert report.docx report.pdf
Enter fullscreen mode Exit fullscreen mode

Expected result: The CLI creates report.pdf if PDF conversion succeeds.

The PDF renderer is part of WordCraft's Rust-based architecture rather than a dependency on a locally installed copy of Microsoft Word.

The project documents PDF export with selectable text, links, and bookmarks.

The precise fidelity of your output still depends on the document's content and the application's current implementation.

Extract document text

WordCraft also provides a text extraction command.

./target/release/wordcraft-cli text report.docx
Enter fullscreen mode Exit fullscreen mode

Expected result: The document's plain-text content appears in the terminal.

You should recognize the project name, completed work, pending tasks, and deployment notes.

This is useful when building document-processing tools that need to read text without opening a graphical editor.

Inspect document structure

Now run:

./target/release/wordcraft-cli inspect report.docx
Enter fullscreen mode Exit fullscreen mode

Expected result: The CLI produces a JSON representation of the document structure.

This is different from extracting plain text.

Document inspection is useful when you need information about content organization rather than only the words themselves.

Possible applications include document validation, automation, testing, and agent workflows.

The exact output structure is determined by the WordCraft CLI implementation, so inspect the real response before integrating it into an application.

Automate report generation from a shell script

Once individual conversions work, a small Bash script can perform them together.

Create export-report.sh:

#!/usr/bin/env bash
set -euo pipefail

CLI="./target/release/wordcraft-cli"

"$CLI" convert report.md report.docx
"$CLI" convert report.docx report.pdf

echo "Document conversion completed."
Enter fullscreen mode Exit fullscreen mode

Execute it:

chmod +x export-report.sh
./export-report.sh
Enter fullscreen mode Exit fullscreen mode

The script stops if a command fails and prints the completion message only after both conversion commands succeed.

This is a useful starting point for local automation.

For production, add temporary working directories, input validation, logging, and checks that the output documents are valid.

Never pass arbitrary user-controlled command strings directly to a shell.

Step 6: Explore WordCraft in the Browser and Compare Alternatives

One of WordCraft's more unusual features is that its Rust-based editor can also target WebAssembly.

That means the project is not limited to running as a traditional desktop application.

Its repository contains a browser application under:

apps/wordcraft-web
Enter fullscreen mode Exit fullscreen mode

Run the browser version locally

The project's documented browser development workflow uses Trunk.

First, install the Rust WebAssembly target:

rustup target add wasm32-unknown-unknown
Enter fullscreen mode Exit fullscreen mode

Install Trunk:

cargo install --locked trunk
Enter fullscreen mode Exit fullscreen mode

From the WordCraft repository root, enter the web application directory:

cd apps/wordcraft-web
Enter fullscreen mode Exit fullscreen mode

Start the development server:

trunk serve
Enter fullscreen mode Exit fullscreen mode

Open the sample document using the URL documented by the repository:

http://127.0.0.1:8771/?sample
Enter fullscreen mode Exit fullscreen mode

Expected result: Assuming the required build dependencies are available and the development server starts successfully, the browser version loads WordCraft's sample editor.

The port above is the project's documented local default; follow the terminal's actual listening address if your configuration differs.

This is a development workflow, not an automatically secured public document service.

If you deploy it for other users, configure appropriate HTTPS hosting, access controls where necessary, and document storage separately.

Don't assume the browser application automatically provides user accounts, collaborative editing, or a Laravel backend.

Can WordCraft connect to AI agents?

Yes. The project also documents a Model Context Protocol (MCP) server.

If you use Claude Code and have its CLI installed, WordCraft's documented registration command is:

claude mcp add wordcraft -- wordcraft-cli mcp
Enter fullscreen mode Exit fullscreen mode

This assumes wordcraft-cli is available on your system's PATH.

Otherwise, provide the executable's absolute path.

The MCP integration exposes operations for creating documents, editing content, inspecting structure, saving files, and rendering pages.

For filesystem safety, the project supports restricting a headless MCP session to specified read and write directories.

See the official WordCraft MCP documentation before allowing an agent to access sensitive files.

How does WordCraft compare with existing tools?

WordCraft enters an already mature market.

Here's the practical comparison:

Tool Best suited for Main consideration
Microsoft Word Professional editing and Word-based collaboration Proprietary software and ecosystem
LibreOffice Writer Established open-source desktop office work Different implementation and compatibility behavior
ONLYOFFICE Docs Office-style editing and document collaboration Server deployment and integration requirements
Pandoc Automated document-format conversion Not a full graphical Word-style editor
PHPWord Generating and manipulating documents in PHP Library rather than an interactive editor
WordCraft Rust-native editing, local automation, DOCX workflows, and experimentation Alpha maturity and incomplete fidelity

For developers, the important distinction is not simply whether an application can open DOCX files.

It's how that application fits into your workflow.

Choose Microsoft Word when exact compatibility with an organization's Word documents is the central requirement.

Choose LibreOffice Writer when you want a mature, open-source desktop editor and its capabilities meet your needs.

Consider ONLYOFFICE Docs when your project needs a web-based office editing solution with collaborative features.

Use Pandoc when your main requirement is repeatable conversion between document formats.

Use PHPWord when a PHP application needs to create structured Word documents programmatically without exposing an editor.

Evaluate WordCraft when you want to explore a newer Rust-based approach combining editing, rendering, CLI operations, and agent control.

Personally, I find its shared document engine and automation interfaces more interesting than the visual resemblance to Microsoft Word.

But that's a technical preference, not a measured claim that WordCraft is faster, more accurate, or more reliable than established alternatives.

The right choice depends on the documents you actually process.

What WordCraft still needs to improve

The project's own roadmap identifies ongoing work involving compatibility with real-world DOCX files, document layout fidelity, stability, and advanced Word features.

Particularly challenging documents may include:

  • Charts and SmartArt.
  • Embedded or specialized objects.
  • Complicated tables and section layouts.
  • Documents relying on particular fonts.
  • Heavily reviewed documents with tracked changes.
  • Files requiring exact pagination across office suites.

The project is moving quickly, so consult the current roadmap and release notes instead of treating an old feature comparison as permanent.

Quick Verification: Check Your WordCraft Installation

Return to the repository root if you're still inside the browser application directory:

cd ../..
Enter fullscreen mode Exit fullscreen mode

Check the CLI:

./target/release/wordcraft-cli --help
Enter fullscreen mode Exit fullscreen mode

Then inspect the files created during the tutorial:

ls -lh report.md report.docx report.pdf
Enter fullscreen mode Exit fullscreen mode

Finally, extract the DOCX content and confirm the report title exists:

./target/release/wordcraft-cli text report.docx \
  | grep -F "Weekly Deployment Report"
Enter fullscreen mode Exit fullscreen mode

Expected result: The CLI responds, all three report files exist, and the final command prints the report title.

Also open report.docx in WordCraft or another compatible word processor and inspect report.pdf visually. Confirm headings, bullets, paragraph spacing, and page layout are acceptable.

Those checks are important because a successful process exit alone does not prove document fidelity.

For higher-confidence validation, repeat the conversion with a representative document containing real tables, images, styles, and page breaks.

Next Steps: Where WordCraft Fits in a Developer Workflow

If WordCraft handles your sample documents reliably, the next experiment is to integrate its CLI into a controlled report-generation pipeline, such as a Laravel queued job, and compare the output with your existing tools. Keep originals and backups, review the project's GitHub repository and roadmap, and evaluate changes against real documents before adopting it for production. WordCraft is an interesting open-source Rust project today; whether it can replace your existing document stack should be decided by testing, not by its GitHub popularity.

Originally published at headsntail.com.

Top comments (0)