PDF.js サーバーサイドにおける Promise.withResolvers エラー解決

環境によってPromise.withResolvers()メソッドがサポートされていない場合に発生するエラーです。Node.js環境でPDF.jsを利用する際の一般的な問題で、主に以下の原因が考えられます。

---

根本原因

1. Node.jsのバージョン互換性問題
   Promise.withResolvers はNode.js v22.0.0以降で実装された機能です。v21以前のバージョンでは未サポート。

2. クライアント向けビルドの使用
   デフォルトのPDF.jsビルドはブラウザ環境向けに最適化されています。サーバーサイド（Node.js）実行にはレガシービルドが必要。

---

推奨解決策：レガシービルドの使用

ステップ1：インポート方法の変更

クライアント向けビルドの代わりにレガシービルドを明示的にインポートします。

// 変更前（問題発生）
import * as pdfjsLib from "pdfjs-dist";

// 変更後（レガシービルド使用）
import * as pdfjsLib from "pdfjs-dist/legacy/build/pdf.min.mjs";

ステップ2：TypeScript型定義の追加

レガシービルド用の型定義ファイルを作成（例：types.d.ts）：

// types.d.ts
declare module 'pdfjs-dist/legacy/build/pdf.min.mjs';

ステップ3：tsconfig.jsonの設定更新

型定義ファイルのパスをコンパイラに認識させます。

{
  "compilerOptions": {
    "typeRoots": [
      "./node_modules/@types",
      "./types" // カスタム型定義ディレクトリ
    ]
  }
}

重要

typeRoots 設定後は開発サーバーの再起動が必要です。設定が反映されない場合、キャッシュクリアを試してください。

---

代替解決策1：Node.jsバージョンのアップグレード

Node.jsをv22以上に更新することでネイティブサポートが有効になります。

# Node.jsバージョンチェック
node -v

# バージョンアップ方法（nvm使用例）
nvm install 22
nvm use 22

注意

プロダクション環境でNode.jsバージョンを変更する場合は、他の依存関係との互換性を必ず検証してください。

---

代替解決策2：Polyfillの実装

一時的な回避策としてグローバルにポリフィルを追加します。

if (typeof Promise.withResolvers === 'undefined') {
  // @ts-ignore
  Promise.withResolvers = function () {
    let resolve: any, reject: any;
    const promise = new Promise((res, rej) => {
      resolve = res;
      reject = rej;
    });
    return { promise, resolve, reject };
  };
}

ワーカーパスの正しい設定方法

// 相対パス解決
pdfjsLib.GlobalWorkerOptions.workerSrc = new URL(
  'pdfjs-dist/legacy/build/pdf.worker.min.mjs',
  import.meta.url
).toString();

// CDN利用例
pdfjsLib.GlobalWorkerOptions.workerSrc =
  "https://unpkg.com/pdfjs-dist@4.4.168/legacy/build/pdf.worker.min.mjs";

---

ベストプラクティスの選択基準

方法	推奨度	適用ケース
レガシービルド使用	★★★★★	全てのNode.js環境・長期運用
Node.js v22以上	★★★☆☆	環境制御可能な新規プロジェクト
Polyfill実装	★★☆☆☆	一時的回避・短期ソリューション

サーバーサイドでPDF.jsを安定利用するにはレガシービルドの使用が最も信頼性が高く、公式ドキュメントでも推奨されています。特にプロダクション環境では、Node.jsバージョンに依存しないこのアプローチを強く推奨します。

ℹ️ 参考資料

• PDF.js公式FAQ: Node.jsサポート
• MDN: Promise.withResolvers()