AIチュートリアル

LibreOffice Kitを使ってNode.jsでOffice文書をPDFおよびPNGに変換する

@deepseek-ai/libreoffice-kitのインストール方法、OfficeファイルのPDF変換、ページのPNG化、スプレッドシートの再計算、フォント設定、Node.jsでのプラットフォーム別エンジン管理について解説します。

2026年10月1日約16分で読了

LibreOffice Kitを使ってNode.jsでOffice文書をPDFおよびPNGに変換する

概要

@deepseek-ai/libreoffice-kitは、ビルド済みで軽量化されたLibreOfficeエンジンを使用してOfficeドキュメントを変換・レンダリングするNode.jsパッケージです。予測可能なドキュメントレイアウト、読みやすいテキスト、明示的なフォント制御、別途インストールしたLibreOfficeに依存しないオフライン実行を必要とするアプリケーション向けに設計されています。

このパッケージは、OfficeからPDFへの変換、PNGへの直接レンダリング、スプレッドシートの再計算に対応しています。Node.jsサービス、デスクトップアプリケーション、バッチ処理ジョブなど、さまざまなドキュメントパイプラインで使用できます。認証、ファイルストレージ、プレビューインターフェースはアプリケーション側で実装する必要があります。

主な機能

Office変換: 対応するWriter、Calc、ImpressドキュメントをPDFにエクスポートします。
ページレンダリング: OfficeまたはPDFの入力をPNGページに直接レンダリングします。
スプレッドシートの再計算: ワークブックを再計算し、更新された結果を保存します。
フォント対応処理: システムフォントを検出するか、明示的に設定したフォントディレクトリをインデックス化します。
置換設定: 一般的なラテン文字および簡体字中国語のフォントファミリーに対するフォールバック設定を使用できます。
不足フォントの報告: 読み取り可能なOOXMLドキュメントデータで宣言されている、利用できないフォントファミリーを報告します。
オフラインエンジン: 対応するmacOSおよびWindowsシステムではパッケージ化されたネイティブエンジンを、LinuxではWASMエンジンを使用します。
リソース制御: タイムアウト、フォントのインデックス化または読み込みの制限を適用します。
コマンドラインおよびNode API: ターミナルから変換を実行するか、アプリケーションコードに統合できます。

対応ドキュメントに関する注意事項

エンジンは、Writer、Calc、Impress、OOXMLおよびバイナリOfficeフィルター、グラフ、レイアウトおよび描画コンポーネント、PDFエクスポートを保持しています。バイナリ形式の.doc、.xls、.pptファイルは、Microsoft Office 97～2003ファイルなど、実際のOLE複合ドキュメントである場合に対応します。

バイナリOffice拡張子に変更しただけのRTFまたはHTMLファイルは受け付けられません。.wpsファイルにも対応していません。

OOXMLドキュメントでは、missingFontsに読み取り可能なドキュメントXML内で見つかった利用できないフォントファミリーが報告されます。バイナリ形式では、LibreOfficeが独自にフォントマッチングを実行する場合でも空のリストが返されます。そのため、この結果は不足グリフの完全なレポートではありません。

前提条件とインストール

Node.js 22.19.0以降が必要です。npmからバージョン0.1.3をインストールします。

npm install @deepseek-ai/libreoffice-kit@0.1.3

このパッケージはオプションの依存関係を使用して、現在のオペレーティングシステムとアーキテクチャに対応するエンジンをインストールします。インストール中にLibreOfficeをコンパイルしたり、追加のエンジンをダウンロードしたり、ユーザーがインストールしたLibreOfficeアプリケーションを検索したりすることはありません。

プラットフォーム別のエンジン選択

macOS Apple Silicon: @deepseek-ai/libreoffice-kit-darwin-arm64を使用します。
macOS Intel: @deepseek-ai/libreoffice-kit-darwin-x64を使用します。
Windows ARM64: @deepseek-ai/libreoffice-kit-win32-arm64を使用し、ARM64版Node.jsとMicrosoft Visual C++ v14 ARM64再頒布可能パッケージが必要です。
Windows x64: @deepseek-ai/libreoffice-kit-win32-x64を使用し、Microsoft Visual C++ v14 x64再頒布可能パッケージが必要です。
Linux: 通常、共有@deepseek-ai/libreoffice-kit-wasmエンジンを使用します。

macOSとWindowsでは対応するネイティブパッケージが必要で、WASMにはフォールバックしません。必要なエンジンがないか破損している場合、createConverterはunavailableエラーで拒否されます。変換に失敗しても、別のエンジンへの自動切り替えは行われません。

コマンドラインインターフェースの使用

インストールするとdsofficeコマンドが追加されます。プロジェクトにローカルインストールした場合は、npm execを介して実行します。

ページをPNGにレンダリングする

次のコマンドは、DOCXドキュメントの1ページ目をreport-pages出力ディレクトリにレンダリングします。

npm exec -- dsoffice render \
  --input report.docx \
  --output-dir report-pages \
  --pages 1

OfficeドキュメントをPDFに変換する

npm exec -- dsoffice convert \
  --input report.docx \
  --output report.pdf

スプレッドシートを再計算する

数式を評価し、更新されたワークブックを保存する必要がある場合は、再計算コマンドを使用します。

npm exec -- dsoffice recalculate \
  --input budget.xlsx \
  --output recalculated.xlsx

Node.js APIによるドキュメント変換

アプリケーションに統合する場合は、createConverterをインポートしてコンバーターを作成し、操作を実行した後、finallyブロックでコンバーターを破棄します。

import { createConverter } from '@deepseek-ai/libreoffice-kit';

const converter = await createConverter({
  timeoutMs: 120_000,
});

try {
  const result = await converter.render({
    inputPath: '/private/work/document.docx',
    outputPath: '/private/work/document.pdf',
  });

  console.log('Backend:', result.backend);
  console.log('Missing fonts:', result.missingFonts);
} finally {
  await converter.dispose();
}

この例では、生成されたPDFがoutputPathに書き込まれます。返される結果には、選択されたバックエンドと、そのドキュメントで検出された不足フォントファミリー名が含まれます。

パスと出力の要件

入力パスと出力パスには絶対パスを指定してください。
呼び出し元アプリケーションが所有および管理するプライベートディレクトリを使用してください。
指定する出力ファイルは、あらかじめ存在していてはいけません。
ネイティブプロセス、ワーカー、プロファイル、一時リソースを確実にクリーンアップできるよう、破棄処理は finally ブロック内に記述してください。

カスタムフォントの設定

デフォルトでは、パッケージは標準的なシステムおよびユーザーのフォントディレクトリからフォントを検出します。代わりに、fontDirectories を使用して明示的なルートディレクトリを指定できます。

import { createConverter } from '@deepseek-ai/libreoffice-kit';

const converter = await createConverter({
  timeoutMs: 120_000,
  fontDirectories: [
    '/absolute/path/to/company-fonts',
    '/absolute/path/to/cjk-fonts',
  ],
});

try {
  const result = await converter.render({
    inputPath: '/private/work/presentation.pptx',
    outputPath: '/private/work/presentation.pdf',
  });

  if (result.missingFonts.length > 0) {
    console.log('Unavailable families:', result.missingFonts);
  }
} finally {
  await converter.dispose();
}

カスタムフォントルートを指定すると、デフォルトの検出リストが拡張されるのではなく、置き換えられます。このパッケージは fontkit を使用してメタデータとグリフカバレッジを調査し、選択したファイルを元のフォントバイト列としてエンジンに提供します。

フォントコレクションはバンドルもダウンロードもされません。デプロイ環境では、適切なフォントを提供し、その再配布権に準拠する必要があります。一般的に、最小構成のコンテナではフォントをインストールするか、明示的なフォントディレクトリを設定する必要があります。

フォールバック動作

デフォルトの fontFallbacks には、一般的なラテン文字および簡体字中国語のフォントファミリーに対する優先設定が含まれています。Calibri が利用できない場合の代替として Carlito、Cambria が利用できない場合の代替として Caladea が含まれます。呼び出し元が指定したフォールバックグループはデフォルトを置き換えます。実際に利用可能なフォントのみを選択でき、フォントをインストールすることはありません。

装飾系や手書き系を含め、インストール済みのフォントファミリーが完全一致する場合は優先されます。WASM のフォント要求にもウェイトとイタリック情報が含まれるため、適切なインストール済み書体の選択に役立ちます。また、フォントカタログから不足しているグリフ用の追加フォントを提供できます。

高度な運用のヒント

コンバーターは慎重に再利用する

コンバーターを再利用すると、変更されていないフォントメタデータ向けの共有インメモリキャッシュおよび容量制限付きのユーザー専用ディスクキャッシュを利用できます。ただし、1つのコンバーター上の操作は直列化されます。サービスで特定の同時実行モデルが必要な場合は、同じコンバーターで複数のレンダリングが同時に実行されると想定せず、この直列化を考慮してください。

各レンダリングでは、引き続き新しいネイティブプロセスまたは Node ワーカーと、プライベートプロファイルが使用されます。キャンセルと破棄は、エンジンの終了およびクリーンアップが完了するまで待機します。

フォントリソースの予算を設定する

大規模または信頼できないフォントディレクトリには、利用可能なフォント制御を使って上限を設定してください。

maxFontFiles は、インデックス化するフォントファイルの数を制限します。
maxFontFileBytes は、個々のフォントファイルのサイズを制限します。
maxLoadedFontBytes は、読み込むフォントデータの合計量を制限します。

すべての操作でフォントが再検出され、再検証されます。変更されていないメタデータは、コンバーターファクトリのキャッシュを通じて共有できます。キャッシュの設定と無効化の詳細については、フォントメタデータキャッシュのドキュメントを参照してください。

Linux のフォント可用性を計画する

Linux の WASM エンジンは、インポートされたフォントのみを使用します。使用可能なフォントがない場合、変換は unavailable で拒否されます。そのため、コンテナには適切なフォントをインストールするか、管理されたフォントディレクトリをマウントし、その絶対パスを fontDirectories に渡してください。

Office と同一の出力を想定しない

フォントを考慮した処理により、ファミリー選択をより細かく制御できますが、Microsoft Office と完全に同一の出力や、ネイティブエンジンと WASM エンジン間で完全に同一の出力が保証されるわけではありません。フォントメトリクスによって、改行位置、ページ割り、表の寸法、その他のレイアウト詳細が変わることがあります。

有意義な比較を行うには、同一のドキュメントバイト列、フォント、エクスポートオプションを使用してください。ネイティブ LibreOffice は、設定された置換を適用する前に、インストール済みの元のファミリーやメトリクス互換の代替フォントを解決する場合があり、書体の選択も独自に行います。

変換をドキュメント処理の境界として扱う

このライブラリは変換とレンダリングを実行しますが、認可、ストレージ、プレビューインターフェースは提供しません。アプリケーション側でアクセスを検証し、呼び出し元が所有するファイルを分離し、プライベートな作業ディレクトリを選択し、変換ジョブに適切な時間およびリソース制限を適用してください。

開発と検証

リポジトリ自体に貢献する場合、LibreOffice をビルドせずにメタデータ、ユニット、パッケージングのチェックを実行できます。

pnpm verify:metadata
pnpm test
pnpm test:packaging

実際のエンジンテストには、アダプタービルド、準備済みのエンジンペイロード、および packages/entry/lib/index.js の絶対パスを指す LIBREOFFICE_RUNTIME_ENTRY が必要です。エンジンのビルドには、リポジトリで固定されているソースおよびツールチェーンのバージョンを使用してください。

まとめ

@deepseek-ai/libreoffice-kit は、Office 変換、スプレッドシートの再計算、PNG レンダリングを最新の Node.js アプリケーションに組み込むための実用的な手段を提供します。主な利点は、明示的なフォント処理と、オフラインで動作する準備済みのネイティブおよび WASM エンジンを組み合わせていることです。信頼性の高い結果を得るには、必要なフォントを用意し、絶対パスのプライベートなパスを使用し、適切な制限を設定し、missingFonts を確認し、使用後は必ずコンバーターを破棄してください。

キャンセル、詳細なエラー処理、追加のリソース制御については、Node API ドキュメントを参照してください。