【ITニュース解説】How to Generate PDFs from HTML with Express and PDF Echo

Webアプリケーションでは、請求書、レポート、チケット、領収書など、さまざまな種類のPDFドキュメントを生成するタスクが頻繁に発生する。これらのPDFは、ユーザーへの情報提供やビジネスプロセスの自動化に不可欠だが、ゼロからPDFを生成するのは非常に手間がかかり、複雑な作業となる場合が多い。この課題に対し、HTMLとCSS、そしてHandlebarsのようなテンプレートエンジンを活用することで、Webページを作成する要領で簡単にコンテンツを設計できる方法が提案されている。さらに、PDF Echoというサービスを利用すれば、これらのHTMLドキュメントを、ユーザーがすぐに利用できるPDFへとシームレスに変換することが可能となる。

この記事では、Node.jsを基盤とし、WebアプリケーションフレームワークのExpress、そしてHandlebarsテンプレートエンジンを組み合わせて請求書を生成し、それをPDF Echoを使ってPDFに変換するプロジェクトの具体的な構築手順を解説している。

まず、Node.jsプロジェクトを初期化する作業から始める。任意のディレクトリでnpm init -yコマンドを実行し、プロジェクトの基本的な設定ファイルであるpackage.jsonを作成する。次に、Webアプリケーションの構築に必要なExpressとExpress Handlebarsという二つのパッケージをnpm install express express-handlebarsコマンドでインストールする。ExpressはWebサーバーの機能を提供し、Express HandlebarsはHandlebarsテンプレートエンジンとExpressを連携させるための役割を担う。

次に、package.jsonファイルにいくつかの設定を追加する。現代のJavaScriptでは、「ECMAScript Modules (ESM)」と呼ばれるモジュールシステムが主流であり、これを使用可能にするために"type": "module"という記述を追加する。これにより、importやexportといった構文を利用できるようになる。また、開発効率を向上させるためのスクリプトも定義する。「start」スクリプトは本番環境でのアプリケーション実行を想定し、「dev」スクリプトは開発中にコードが変更されるたびに自動的にアプリケーションを再起動する「ウォッチモード」で実行されるように設定される。

続いて、ExpressとHandlebarsを構成する。src/app.jsファイル内でExpressアプリケーションのインスタンスを作成し、Handlebarsをテンプレートエンジンとして登録する。具体的には、app.engine('hbs', engine({ defaultLayout: false }))で、.hbsという拡張子を持つファイルをHandlebarsで処理するように設定し、デフォルトのレイアウト機能を無効にする。さらに、app.set('view engine', 'hbs')でHandlebarsをビューエンジンとして設定し、app.set('views', path.join('src', 'views'))でテンプレートファイルがsrc/viewsディレクトリに格納されることをExpressに伝える。src/index.jsファイルでは、app.jsで定義されたExpressアプリケーションをインポートし、環境変数またはデフォルトで設定されたポート番号（通常は4000番）でWebサーバーを起動する。

次に、Handlebarsを使って請求書のテンプレートを設計する。src/views/invoice.hbsというファイルに、HTMLとCSSを用いて請求書の視覚的なレイアウトとスタイルを記述する。このテンプレートには、顧客名、日付、商品リスト、合計金額など、動的に挿入されるべきデータのプレースホルダーが含まれる。例えば、{{customer_name}}は顧客名が、{{#each items}}は商品リストがそれぞれ表示される部分を示す。また、{{multiply unit_price quantity}}のように、テンプレート内で簡単な計算を実行するための「カスタムヘルパー」も定義されている。これらのカスタムヘルパー（sum、multiply、calculateTax）は、テンプレートがレンダリングされる前にExpressアプリケーションのHandlebarsエンジンに登録する必要がある。src/app.jsのHandlebarsエンジンの設定箇所に、これらのヘルパー関数をJavaScriptコードとして定義する。これにより、Handlebarsはテンプレート内の動的な計算を正しく処理し、結果をHTMLに組み込むことが可能となる。

Handlebarsテンプレートが意図通りに機能するかを確認するため、PDF Echoと連携する前に、ブラウザでHTMLをレンダリングするルートを作成する。Expressサーバーに/invoiceというGETリクエストを処理するルートを設定し、このルート内で請求書表示用のモックデータ（ダミーデータ）を用意する。このモックデータには、顧客情報、商品リスト、税率などの詳細が含まれる。このルートでは、res.render('invoice', {...モックデータ...})メソッドを使用して、モックデータをテンプレートに適用し、レンダリングされたHTMLをブラウザに送信する。Webブラウザでhttp://localhost:4000/invoiceにアクセスすると、モックデータが適用された請求書のHTMLが正しく表示されることを確認できる。このステップは、PDF変換前のテンプレートのデザインやヘルパー関数の動作検証に非常に有効である。

テンプレートがブラウザで正常にレンダリングされることを確認した後、いよいよPDF Echoとの連携を通じて実際のPDFを生成する段階に入る。Expressサーバーに/invoice/pdfという新しいGETリクエストルートを追加する。このルートも、先ほどと同様にモックデータを用いてテンプレートをレンダリングするが、今回はres.render()メソッドの3番目の引数としてコールバック関数を指定する。このコールバック関数は、テンプレートが完全にHTML文字列としてレンダリングされた直後に実行され、その結果のHTML文字列を受け取ることができる。

取得したHTML文字列は、次にPDF EchoのAPIに送信される。JavaScriptのfetch関数を使用して、PDF EchoのAPIエンドポイントhttps://api.pdfecho.comにPOSTリクエストを送信する。リクエストのボディには、sourceというキーにレンダリングされたHTML文字列を値として持つJSONオブジェクトを含める。APIへの認証のためには、Authorizationヘッダーを設定する必要があり、これにはPDF EchoのAPIキーをBase64でエンコードした情報を含める。開発中は、'pe-test-mode': 'true'ヘッダーを追加することで、テストモードでAPIを利用できる。

PDF Echo APIからの応答は、PDFドキュメントのバイナリデータとして返される。このバイナリデータはrequest.arrayBuffer()で取得され、Node.jsのBufferオブジェクトに変換される。最後に、Expressのres.contentType('Content-Type', 'application/pdf').send(Buffer.from(data))メソッドを使って、このPDFデータをクライアント（ブラウザ）に送信する。これにより、ブラウザは受け取ったデータをPDFファイルとして認識し、自動的にダウンロードするか、ブラウザ内で表示する。http://localhost:4000/invoice/pdfにアクセスすると、モックデータに基づいて生成された請求書のPDFがダウンロードされることを確認できる。

この一連の作業を通じて、Node.js、Express、Handlebars、そしてPDF Echoを組み合わせることで、動的なHTMLコンテンツから高品質なPDFドキュメントを効率的に生成するバックエンドシステムを構築できる。このシステムは、リアルタイムでのPDF生成を可能にし、請求書の発行、レポートの作成、契約書の生成といった多岐にわたるビジネス要件に対応できる柔軟な基盤を提供する。さらに、PDF Echoは、生成されたPDFをAWS S3やGoogle Cloud Storageのようなクラウドストレージサービスに直接保存したり、PDF生成完了時にWebhookを使ってアプリケーションに通知したりするなど、さらなる拡張オプションも提供しており、これにより、より高度な自動化とワークフローの構築が可能となる。