Node.js PDF ライブラリ — PDF Oxide

PDF Oxide は Node.js 向けの最速 PDF ライブラリです。テキスト抽出はページ平均 0.8 ms、PyMuPDF の 5 倍、pypdf の 15 倍高速、3,830 件の PDF でパス率 100%。抽出・作成・編集をひとつのパッケージに、TypeScript 型定義付き。ライセンスは MIT / Apache-2.0 です。

ブラウザ、Deno、Bun、Cloudflare Workers で動かしますか？ 代わりに WASM ビルド をご利用ください。同じ API、ネイティブバイナリ不要です。このページの N-API アドオンは Node.js と Electron 向けです。

インストール

npm install pdf-oxide

要件: Node.js 18 以降。システム依存や Rust ツールチェーンは不要です。Linux（glibc + musl）x64/arm64、macOS x64/arm64、Windows x64/arm64 向けのプリビルト .node アドオンをプラットフォーム別の optionalDependencies から自動取得します。インストール時にコンパイルは走りません。

PDF を開く

JavaScript

const { PdfDocument } = require("pdf-oxide");

const doc = new PdfDocument("research-paper.pdf");
console.log(`Pages: ${doc.getPageCount()}`);

const { major, minor } = doc.getVersion();
console.log(`PDF version: ${major}.${minor}`);

doc.close();

TypeScript

import { PdfDocument } from "pdf-oxide";

const doc: PdfDocument = new PdfDocument("research-paper.pdf");
const pageCount: number = doc.getPageCount();
const { major, minor }: { major: number; minor: number } = doc.getVersion();
console.log(`${pageCount} pages, PDF ${major}.${minor}`);
doc.close();

Node.js 22 以降では using を使って自動クリーンアップできます。

{
  using doc = new PdfDocument("report.pdf");
  const text = doc.extractText(0);
} // doc.close() が自動で呼ばれる

Page API

v0.3.34 から PdfDocument はイテラブルになり、doc.page(i) は width / height / rotation をキャッシュした PdfPage を返します。ページ単位の抽出メソッドも使えます。

const { PdfDocument } = require("pdf-oxide");

const doc = new PdfDocument("paper.pdf");
for (const page of doc) {
  console.log(`Page ${page.index}: ${page.width}x${page.height} (rotation ${page.rotation})`);
  const md = page.markdown();
  const tables = page.tables();       // 行とセル、bbox 付き
}
doc.close();

インデックス指定: doc.page(0)、doc.page(-1)（最終ページ）。ページメソッド: text()、markdown()、html()、plainText()、words()、lines()、tables()、images()、paths()、annotations()、fonts()、search(query, caseSensitive)。

テキスト抽出

単一ページ

JavaScript

const { PdfDocument } = require("pdf-oxide");

const doc = new PdfDocument("report.pdf");
const text = doc.extractText(0);
console.log(text);
doc.close();

TypeScript

import { PdfDocument } from "pdf-oxide";

const doc: PdfDocument = new PdfDocument("report.pdf");
const text: string = doc.extractText(0);
console.log(text);
doc.close();

全ページ

const doc = new PdfDocument("book.pdf");
const pageCount = doc.getPageCount();

for (let i = 0; i < pageCount; i++) {
  console.log(`--- Page ${i + 1} ---`);
  console.log(doc.extractText(i));
}

doc.close();

非同期抽出

同期メソッドにはそれぞれ libuv のスレッドプールで動作する *Async 版があります。HTTP ハンドラのように並行処理を行うサーバーコードでは、これを使うことでイベントループをブロックせずに抽出できます。

const { PdfDocument } = require("pdf-oxide");

async function extract(path) {
  const doc = new PdfDocument(path);
  try {
    return await doc.extractTextAsync(0);
  } finally {
    doc.close();
  }
}

ページごとに Promise.all でファンアウトするパターンは 非同期ガイド を参照してください。

構造化抽出

文字レベル・スパンレベルで、位置情報とフォントメタデータを取得できます。

const chars = doc.extractChars(0);
for (const ch of chars.slice(0, 10)) {
  console.log(`'${ch.char}' at (${ch.x.toFixed(1)}, ${ch.y.toFixed(1)}) ` +
              `size=${ch.fontSize.toFixed(1)} font=${ch.fontName}`);
}

const spans = doc.extractSpans(0);
for (const span of spans) {
  console.log(`"${span.text}" font=${span.fontName} size=${span.fontSize}`);
}

しきい値を調整できる単語・行単位の抽出:

const words = doc.extractWords(0);
const lines = doc.extractTextLines(0, { wordGapThreshold: 2.5, lineGapThreshold: 1.2 });

Markdown 変換

JavaScript

const md = doc.toMarkdown(0, { detectHeadings: true });
console.log(md);

// 全ページ
const allMd = doc.toMarkdownAll();

TypeScript

const md: string = doc.toMarkdown(0, { detectHeadings: true });
const allMd: string = doc.toMarkdownAll();

HTML 変換

const html = doc.toHtml(0);
const allHtml = doc.toHtmlAll();

画像抽出

const { writeFileSync } = require("fs");

const doc = new PdfDocument("brochure.pdf");
const images = doc.extractImages(0);

for (const [i, img] of images.entries()) {
  console.log(`Image ${i}: ${img.width}x${img.height} ${img.format} (${img.data.length} bytes)`);
  writeFileSync(`image_${i}.${img.format}`, img.data);
}

doc.close();

Indexed カラーの PDF から取り出した画像は自動で RGB に展開されます。1/2/4/8 bpc のインデックスパレットと RGB・グレースケール・CMYK のベース色空間に対応しています。

バイト列から開く

メモリ上のバイト列から PDF を開けます。S3・HTTP・データベースから取得したバイナリに便利です。

const { PdfDocument } = require("pdf-oxide");
const { readFileSync } = require("fs");

const bytes = readFileSync("document.pdf");
const doc = PdfDocument.openFromBytes(bytes);
const text = doc.extractText(0);
doc.close();

パスワード付き PDF

const doc = PdfDocument.openWithPassword("confidential.pdf", "secret");
const text = doc.extractText(0);
doc.close();

開いたあとに認証することもできます。

const doc = new PdfDocument("confidential.pdf");
if (doc.authenticate("secret")) {
  console.log(doc.extractText(0));
}
doc.close();

AES-256（V=5, R=6）の PDF にも完全対応しています。プッシュボタンウィジェットのキャプション、遅延認証後に正しく無効化されるオブジェクトキャッシュも含めて動作します。

PDF の作成

Pdf クラスには、さまざまな入力形式から PDF を生成するファクトリメソッドが揃っています。

Markdown から

const { Pdf } = require("pdf-oxide");
const { writeFileSync } = require("fs");

const pdf = Pdf.fromMarkdown("# Hello World\n\nThis is a PDF.");
writeFileSync("output.pdf", pdf.toBytes());

HTML から

const pdf = Pdf.fromHtml("<h1>Invoice</h1><p>Amount due: $42.00</p>");
writeFileSync("invoice.pdf", pdf.toBytes());

プレーンテキストから

const pdf = Pdf.fromText("Plain text document.\n\nSecond paragraph.");
writeFileSync("notes.pdf", pdf.toBytes());

画像から

const pdf = Pdf.fromImage("scan.jpg");
writeFileSync("scan.pdf", pdf.toBytes());

検索

const doc = new PdfDocument("manual.pdf");

// 全ページを検索
const results = doc.searchAll("configuration", { caseSensitive: false });
for (const r of results) {
  console.log(`Page ${r.page}: "${r.text}" at (${r.x.toFixed(0)}, ${r.y.toFixed(0)})`);
}

// 単一ページを検索
const pageResults = doc.searchPage(0, "configuration");
doc.close();

大きな文書をストリーミング検索する場合は SearchStream を使います。

const { PdfDocument, SearchStream, SearchManager } = require("pdf-oxide");

const doc = new PdfDocument("large.pdf");
const manager = new SearchManager(doc);
const stream = new SearchStream(manager, "invoice");

stream.on("data", (r) => console.log(`page ${r.pageIndex + 1}: ${r.text}`));
stream.on("end", () => doc.close());

詳細は Node.js ストリームガイド を参照してください。

編集

メタデータ、ページ操作、注釈、フォームフィールドの編集には DocumentEditor を使います。

const { DocumentEditor } = require("pdf-oxide");

const editor = DocumentEditor.open("document.pdf");

// メタデータ
editor.setTitle("Updated Title");
editor.setAuthor("Jane Doe");

// ページ操作
editor.rotatePage(0, 90);
editor.deletePage(5);
editor.movePage(2, 0);

// フォーム
editor.setFormFieldValue("employee.name", "Jane Doe");
editor.flattenForms();

editor.save("edited.pdf");
editor.close();

OCR

スキャンされたページで OCR を使うには、インストール時に ocr フィーチャを有効化します。

npm install pdf-oxide --build-from-source -- --features ocr

const { PdfDocument, OcrEngine } = require("pdf-oxide");

const doc = new PdfDocument("scanned.pdf");
const ocr = new OcrEngine();

if (ocr.pageNeedsOcr(doc, 0)) {
  const text = ocr.extractText(doc, 0);
  console.log(text);
}

ocr.close();
doc.close();

エンドツーエンドの手順は OCR ガイド を参照してください。

スレッド安全性

PdfDocument は Send + Sync を満たしており、単一のドキュメントを複数のワーカースレッド間で共有し並列にページを読み込めます。*Async 系は libuv のスレッドプールを使って自動的にこれを行います。手動のワーカー構成については 並行処理 を参照してください。

エラー処理

どのメソッドも失敗時には例外を投げます。

const { PdfDocument } = require("pdf-oxide");

try {
  const doc = new PdfDocument("document.pdf");
  const text = doc.extractText(0);
  doc.close();
} catch (err) {
  console.error(`Extraction failed: ${err.message}`);
}

次のステップ

• Python 入門 — Python から PDF Oxide を使う
• WASM 入門 — ブラウザ / Deno / Bun / エッジランタイム
• Node.js API リファレンス — ネイティブ API の完全ドキュメント
• 非同期ガイド — *Async メソッドと Promise.all パターン
• Node.js ストリーム — SearchStream 他
• テキスト抽出 — 抽出オプションの詳細