Node.js で PDF を生成:Puppeteer、PDFKit、jsPDF
Puppeteer で HTML レポートを印刷したり、PDFKit でデータから文書を描画したり、jsPDF と html2canvas でブラウザー要素の画像をダウンロードしたりできます。これらのオープンソースのサンプルが生成する PDF は、テキストとレイアウトの特性が異なります。エクスポート方法を選ぶ際には、この違いが重要です。
ここで扱うのは PDF の生成であり、汎用的な文書変換ではありません。どのサンプルも、Word、スプレッドシート、PDF のファイルを別の編集可能な形式に変換するものではありません。
適切なライブラリの選択
| 入力 | サンプル | 想定される出力 |
|---|---|---|
| CSS を含むローカル HTML | Puppeteer | テキストを選択できる A4 の印刷レイアウト |
| 文字列と描画命令 | PDFKit | テキストを選択できる A4 文書。座標は自分で指定 |
| ブラウザー要素 | jsPDF + html2canvas | A4 の単一ページに収まる画像。テキストの選択は不可 |
サンプルのセットアップ
これらのサンプルは、Linux 上の Node.js 26.8.1、Yarn 4.12.0、Puppeteer の Chrome for Testing 151.0.7922.71 でテストしました。手順を再現するには、これらのテスト済みバージョンを使用してください。ライブラリの最小要件を示すものではありません。プロジェクトを作成する前に、Corepack と unzip をインストールしておく必要があります。Yarn インストールガイドを参照してください。corepack --version が失敗する場合は、同ガイドに従ってください。Chrome には、Puppeteer のシステム要件に記載されたシステムライブラリも必要です。
書き込み可能なディレクトリから、次のコードを Bash に貼り付けてください。パッケージとブラウザーのローカルキャッシュを持つ独立したプロジェクトを作成し、元のディレクトリに戻ります。既存の node-pdf-demo は変更しません。作成後にインストールが失敗した場合は、報告された問題を修正し、そのフォルダー内で
corepack yarn コマンドを両方とも再実行してください。再作成は不要です。
(
corepack --version &&
unzip -v >/dev/null &&
mkdir node-pdf-demo &&
cd node-pdf-demo &&
printf '%s\n' '{"private":true,"packageManager":"yarn@4.12.0"}' > package.json &&
touch yarn.lock &&
printf '%s\n' 'nodeLinker: node-modules' 'enableGlobalCache: false' > .yarnrc.yml &&
PUPPETEER_CACHE_DIR="$PWD/.puppeteer" corepack yarn add --exact \
puppeteer@25.5.0 pdfkit@0.17.2 jspdf@4.2.1 html2canvas@1.4.1 &&
PUPPETEER_CACHE_DIR="$PWD/.puppeteer" corepack yarn exec puppeteer browsers install chrome
)
ブラウザーを明示的にインストールする方法は、依存関係のインストールスクリプトが無効でも機能します。この違いは Puppeteer のインストールガイドで説明されています。以下のファイルを node-pdf-demo に保存し、そのディレクトリから Node コマンドを実行してください。.cjs 拡張子により、ES モジュールのプロジェクト内でもサーバー側のサンプルは CommonJS として扱われます。
Puppeteer による HTML から PDF への変換
Puppeteer は Chrome の印刷レンダラーを使用します。page.pdf() メソッドはデフォルトで印刷用 CSS を使用するため、PDF が画面のレイアウトと異なる場合があります。このサンプルでは、ローカルの自己完結した HTML だけを使用します。自分で管理する HTML をレンダリングしてください。任意の URL や信頼できないスクリプトを受け付けるサービスとして使うものではありません。
ローカルレポートの印刷
次の内容を report.html として保存してください。
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Puppeteer report</title>
<style>
body { margin: 0; font-family: Arial, sans-serif; }
main { padding: 32px; }
h1 { font-size: 28px; }
.marker { height: 24px; background: #c81e50; }
footer { margin-top: 160px; }
</style>
</head>
<body>
<main>
<h1>Hello, Puppeteer!</h1>
<p>This report keeps its text selectable.</p>
<div class="marker"></div>
<footer>End of report.</footer>
</main>
</body>
</html>
次の内容を html-to-pdf.cjs として保存してください。
const { pathToFileURL } = require('node:url')
const puppeteer = require('puppeteer')
async function htmlToPdf(url, outputPath) {
const browser = await puppeteer.launch()
try {
const page = await browser.newPage()
const response = await page.goto(url, { waitUntil: 'networkidle0' })
if (!response || !response.ok()) {
throw new Error(`Page load failed: ${response?.status() ?? 'no HTTP response'}`)
}
await page.pdf({
path: outputPath,
format: 'A4',
printBackground: true,
margin: { top: '10mm', right: '10mm', bottom: '10mm', left: '10mm' },
})
} finally {
await browser.close()
}
}
const inputUrl = pathToFileURL(process.argv[2] ?? 'report.html').href
htmlToPdf(inputUrl, process.argv[3] ?? 'puppeteer.pdf').catch((error) => {
console.error(error.message)
process.exitCode = 1
})
PUPPETEER_CACHE_DIR="$PWD/.puppeteer" node html-to-pdf.cjs report.html puppeteer.pdf
puppeteer.pdf を開いてください。単一ページに色付きのバーがあり、本文の下に End of report. が表示されるはずです。Hello, Puppeteer! を選択してコピーし、画像ではなくテキストであることを確認してください。printBackground: true により、CSS のバーが含まれます。長い HTML は印刷ページをまたいで配置されます。独自の改ページには印刷用スタイルを追加してください。ネットワークがアイドル状態でも、アプリケーションの更新がすべて完了したとは限らないため、動的なページには独自の準備完了条件が必要です。
PDFKit による PDF の生成
PDFKit は描画 API とテキスト API でコンテンツを作成します。HTML や CSS は解釈しません。データがあり、そのデータをページ上のどこに配置するか制御したい場合に適しています。入門ガイドでは、文書ストリームとページオプションを説明しています。
文書の描画
次の内容を create-pdf.cjs として保存してください。pipeline() を待つことで、プログラムの完了前に出力ストリームのエラーを報告します。
const PDFDocument = require('pdfkit')
const fs = require('node:fs')
const { pipeline } = require('node:stream/promises')
async function createPdf(outputPath) {
const doc = new PDFDocument({ size: 'A4' })
const writing = pipeline(doc, fs.createWriteStream(outputPath))
try {
doc.fontSize(25).text('Hello, PDFKit!', 100, 100)
doc.fontSize(12).text('This is a sample PDF generated using PDFKit.', 100, 150)
doc.text('End of report.', 100, 350)
doc.end()
} catch (error) {
doc.destroy(error)
}
await writing
}
createPdf(process.argv[2] ?? 'pdfkit.pdf').catch((error) => {
console.error(error.message)
process.exitCode = 1
})
node create-pdf.cjs pdfkit.pdf
pdfkit.pdf を開き、見出しの
Hello, PDFKit! をコピーしてみてください。テキストの三行が A4 の単一ページに収まるはずです。座標の単位は PDF ポイントで、1 インチは 72 ポイントです。PDFKit はテキストを折り返せますが、表や繰り返しヘッダーを含む文書には、別途レイアウトのロジックが必要です。HTML テンプレートをこれらの API にそのまま流用することはできません。
どちらの Node コマンドも、書き込みの開始時に既存の出力先を置き換えます。入力が見つからない場合やブラウザーの起動に失敗した場合は、以前の PDF が変更されずに残ることがあり、書き込みに失敗した場合は、不完全なファイルが残ることがあります。以前のエクスポートを保持する必要がある場合は、新しいファイル名を使用してください。エラー処理を確認するには、存在しないディレクトリ内のパスを出力先として渡してください。コマンドがエラーを報告し、ゼロ以外の終了コードで終了するはずです。
jsPDF によるクライアント側での PDF 生成
jsPDF はテキストベースの PDF も作成できます。ここでは、html2canvas が単一の HTML 要素をキャンバスに描画し、jsPDF がそのキャンバスを画像として埋め込みます。html2canvas は対応する DOM と CSS のプロパティから要素を再構築します。ブラウザーのスクリーンショットと異なる場合がある理由は、ドキュメントで説明されています。
ブラウザー要素の画像のダウンロード
次の完全なファイルを browser-pdf.html として
node_modules と同じディレクトリに保存し、Chrome で開いてください。
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Browser PDF export</title>
<style>
#content { box-sizing: border-box; width: 640px; padding: 32px; font: 16px Arial; }
h1 { font-size: 28px; }
.marker { height: 24px; background: #c81e50; }
footer { margin-top: 160px; }
</style>
</head>
<body>
<script src="./node_modules/jspdf/dist/jspdf.umd.min.js"></script>
<script src="./node_modules/html2canvas/dist/html2canvas.min.js"></script>
<main id="content">
<h1>Hello, jsPDF!</h1>
<p>This report is exported as an image.</p>
<div class="marker"></div>
<footer>End of report.</footer>
</main>
<button id="download">Download PDF</button>
<p id="status" role="status"></p>
<script>
async function generatePDF() {
const { jsPDF } = window.jspdf
const content = document.getElementById('content')
const canvas = await html2canvas(content, { scale: 2, backgroundColor: '#ffffff' })
const imgData = canvas.toDataURL('image/png')
const pdf = new jsPDF()
const width = pdf.internal.pageSize.getWidth() - 20
const height = pdf.internal.pageSize.getHeight() - 20
const scale = Math.min(width / canvas.width, height / canvas.height)
pdf.addImage(imgData, 'PNG', 10, 10, canvas.width * scale, canvas.height * scale)
await pdf.save('download.pdf', { returnPromise: true })
}
const button = document.getElementById('download')
button.addEventListener('click', async () => {
if (button.disabled) return
button.disabled = true
const status = document.getElementById('status')
status.textContent = ''
try {
await generatePDF()
status.textContent = 'Download requested.'
} catch {
status.textContent = 'Unable to generate the PDF. Please try again.'
} finally {
button.disabled = false
}
})
</script>
</body>
</html>
Download PDF をクリックしてください。画像の生成中はボタンが無効になり、その後ページに
Download requested. と表示されます。このメッセージは保存リクエストが発行されたことを示します。ブラウザーのダウンロード一覧で download.pdf を確認してください。jsPDF プロジェクトには、ブラウザー用ビルドの説明があります。
ダウンロードしたファイルを開き、見出し、色付きのバー、フッターを確認してください。すべてページの余白内に表示されるはずですが、見出しをテキストとして選択することはできません。このサンプルはページ分割せず、画像全体を単一ページに縮小するため、長いレポートは小さくなります。検索可能なテキストが必要な場合は、Puppeteer またはテキストベースのレイアウトを使用してください。また、この画像にはスクリーンリーダー向けの元の HTML の意味構造がありません。外部画像には、適切な同一オリジンまたは CORS の設定が必要です。このサンプルでは画像や Web フォントを使用していません。
wkhtmltopdf の利用はレガシーワークフローに限定
wkhtmltopdf は、古い Qt WebKit エンジンで HTML を PDF に変換します。リポジトリは 2023年1月にアーカイブされ、現在はメンテナンスされていません。既存のインストール環境では、信頼できる HTML だけを扱ってください。プロジェクトのセキュリティガイドでも、信頼できない入力について警告しています。既存のインストール環境では、実際に使用するバイナリとフォントで、自分の信頼できるテンプレートをテストしてください。上記のサンプルは、このレンダラーを検証するものではありません。新たに HTML から PDF への変換を実装する場合は、Puppeteer などのメンテナンスされているレンダラーを使用してください。
