---

ひとことで言うと

docx-vellum は、.docx ファイルをサーバー往復なしでブラウザ上にレンダリングするTypeScriptライブラリです。Open XML（.docx）を解析し、ページ分割されたHTMLを直接DOMコンテナへ描き出します。

[[recon]] という文書バージョン管理システムのプレビューエンジンとして生まれ、現在はそこから切り出して、単体でpublishできる独立npmパッケージへと育てているところです。Reconが「差分を計算する」なら、docx-vellumは「その文書を実際に画面へ描く」役割を担います。

---

どんな課題を解決するのか

文書を扱うWebアプリで「Wordプレビュー」を出そうとすると、たいていの選択肢はサーバー側変換に行き着きます。LibreOfficeをヘッドレスで回す、外部APIにdocxを投げてPNG/PDFを受け取る — どれもファイルをサーバーに送ることを意味します。

機密文書を扱う場面では、これは大きな制約です。docx-vellumは描画を完全にクライアントサイドで完結させます。.docx のバイト列がブラウザの外に出ない。これは、文書VCSであるReconがWebView内で差分プレビューを安全に出すための、絶対条件でした。

---

何ができるのか

import { renderSync } from "docx-vellum";

const blob = await (await fetch("/sample.docx")).blob();
const body  = document.getElementById("document-container");
const style = document.getElementById("style-container");

// 解析 → ページ分割HTMLを body に描画
const doc = await renderSync(blob, body, style, { breakPages: true });

主なAPI:

• parseAsync(data, options?) — docx（Blob / ArrayBuffer / Uint8Array）を描画せず WordDocument モデルへ解析
• renderSync(...) — 同期・ページネーション対応レンダラで解析＋描画
• renderAsync(...) — upstream由来の非同期レンダラ（互換用）
• renderDocument(doc, ...) — 解析済みモデルを描画

ESM / CJS / UMD の3形態をバンドルし、.d.ts も同梱。バンドラ経由でも、CDNから <script> で読み込むグローバル（docx）としても使えます。

---

由来とライセンスへの誠実さ

docx-vellumは、millet0328氏の docx-preview-sync のフォークであり、それ自体が Volodymyr Baydalka氏の docx-preview / docxjs から派生したものです。両プロジェクトは Apache-2.0 ライセンスで、このフォークもそれを引き継いでいます。

OSSの系譜を曖昧にせず、NOTICE ファイルで帰属を明記する — これは、サブセットであることを隠さない[[fluxa-webcp]]と同じ、設計上の誠実さだと考えています。「どこまでが先人の仕事で、どこからが自分の拡張か」をはっきりさせることは、ライブラリ作者の責任です。

---

技術的な裏側 と 現在地

• 言語 — TypeScript。ランタイム依存は jszip（ZIP展開）、konva（描画）、lodash-es を通常依存として宣言
• ビルド — Rollupで ESM / CJS / UMD を出力。.d.ts 同梱
• テスト — Vitestによるユニットテストに加え、Playwright による実ブラウザでの描画回帰テスト。tests/golden/*.html をgolden出力として、レンダリング結果のリグレッションを検出
• ステータス — 0.x。現行の renderSync / renderAsync はupstream由来の入口で、今後**構造化された RenderResult（ページハンドル / ソースマップ / オーバーレイ層）**へと再設計予定。依存する場合はバージョン固定を推奨

upstreamの「とにかく描く」段階から、**Reconが必要とする「差分のbefore/afterを重ねて見せる」**ための土台 — ページハンドルやオーバーレイ層 — へ進化させている最中です。フォークを単に使うのではなく、自分のユースケースに向けて作り変えていく過程そのものが、このプロジェクトの中身です。

リンク

• GitHub