pdfcn とは?shadcn CLI で導入する React 向け PDF コンポーネント集の使いどころ

pdfcn は、React で請求書やレポートなどの PDF を作るためのコンポーネント集です。npm パッケージとして依存に追加するのではなく、shadcn CLI でコードを自分のプロジェクトにコピーして所有する形で配布されています。PDF の描画は Takumi と Forme という 2 つのレンダラーのどちらかに任せる設計で、いずれもヘッドレスブラウザを立ち上げずに PDF を生成します。ライセンスは MIT です。React スタックで帳票 PDF を作る必要があり、外部 API に書類データを送りたくない場合に検討対象になります。
pdfcn の正体は「PDF 用の shadcn レジストリ」
pdfcn は shadcn-labs という GitHub organization で公開されているプロジェクトで、shadcn/ui 本体(shadcn-ui organization)とは別の取り組みです。作者は Aniket Pawar 氏。公式サイトでは pnpm dlx shadcn@latest add @pdfcn/takumi/page-header のようなコマンドが提示され、ページヘッダー、キーバリュー表示、テーブル、セクション、テキスト、ページフッター、アラートといった部品を個別に追加できます。請求書・財務レポートなど複数部品を組み合わせた「ブロック」やテーマ、テーマビルダーも用意されています。
ここで重要なのは、インストール後にコードが自分のリポジトリに入るという点です。ライブラリのバージョンアップを待たずにレイアウトや文言を直せる一方、上流の改善を自動で受け取ることはできません。shadcn/ui を使っているチームなら運用感覚はそのまま流用できます。
導入前に押さえる 2 つの前提
ひとつは名前空間の設定です。@pdfcn/... という指定は shadcn の名前空間付きレジストリの記法で、通常はプロジェクトの components.json の registries フィールドに URL テンプレートを登録して使います。公式のレジストリインデックスに登録済みの名前空間であれば、shadcn add や shadcn search の実行時に CLI がインデックスを参照して components.json に追記します。初回のコマンドで「レジストリが未設定」と言われた場合は、手動で登録すれば解決します。
もうひとつはレンダラーの選択です。pdfcn の部品はレンダラーごとの名前空間に分かれているため、Takumi 用と Forme 用のどちらを入れるかを先に決める必要があります。後から乗り換える場合、コンポーネントの入れ替えとテンプレートの書き直しが発生します。
Takumi と Forme はどう違うか
Takumi(takumi-pdf)は JSX・HTML・ノードツリーを PDF に変換します。レイアウトは CSS と Tailwind で書き、render() が Uint8Array を返します。用紙は a3〜a5、letter、legal に加えて jis-b4・jis-b5 もキーワードで指定でき、余白は既定で auto、ヘッダー・フッターの高さに合わせて調整されます。フッターに PageNumber と TotalPages を置けばページ番号が入ります。Node.js・Bun・Cloudflare Workers で動き、Next.js のルートハンドラ向けに takumi-pdf/next エントリ、ブラウザ向けに WASM を明示初期化する経路も用意されています。CSS の @page ルールは解釈されないため、用紙設定はオプションで渡します。
Forme(@formepdf/react など)は Document / Page / View / Text を style プロパティで組み立てる、react-pdf に近い書き方です。CLI に開発サーバーが付属し、npx @formepdf/cli dev invoice.tsx で PDF プレビューをライブリロードしながら、要素の境界・余白・改ページ位置をオーバーレイ表示できます。Svelte と Vue のアダプタ、入力可能フォームや PDF/UA(アクセシビリティ)、PDF/A(長期保存)、電子証明といった機能がドキュメントで案内されています。
選び方の目安はスタイリングの流儀です。Tailwind と CSS の知識をそのまま使いたい、既存の HTML テンプレートを流用したいなら Takumi。style オブジェクトで厳密に組みたい、改ページのデバッグ環境を重視するなら Forme が合います。なお Takumi も PDF/A・PDF/UA のガイドを持っています。要件に PDF/A や PDF/UA、フォーム入力が含まれる場合は、レンダラー側のドキュメントとライセンス・利用条件を先に確認してください。
日本語の帳票で先に確認すべきこと
ヘッドレスブラウザを使わない方式では、フォントを明示的に登録しない限り文字は描画できません。Takumi では googleFonts ヘルパーや PdfRenderer.registerFont() でフォントを登録し、登録したフォントはサブセットとして埋め込まれます。日本語の帳票では、Noto Sans JP のような和文フォントを登録する前提で設計してください。CJK フォントはファイルサイズが大きいため、サブセット後の PDF サイズと生成時間は早い段階で実測しておくのが安全です。
あわせて、金額の桁区切り、縦方向に伸びる明細行の改ページ、印影や QR コードの配置といった日本の帳票固有の要件を、サンプルデータではなく本番に近いデータで検証することをおすすめします。
採用するか見送るかの判断基準
pdfcn が向くのは、React(特に Next.js)のアプリ内で PDF を生成し、書類データを自社インフラの外に出したくないケースです。ドキュメント単位課金の外部 PDF API と違い、生成量が増えても費用が比例しません。サイトは llms.txt や各ページの Markdown 版、エージェント用スキルを公開しており、AI コーディングツールに読ませながら組み立てる進め方とも相性が良い構成になっています。
一方で見送る理由もはっきりしています。React のレンダリング環境が前提のため、PHP や Rails などのサーバーサイドテンプレートだけで完結している構成には直接持ち込めません。リポジトリのコミット数はまだ 50 件弱で、公開から日が浅いプロジェクトです。加えて、出力品質と不具合修正は Takumi と Forme という別プロジェクトに依存します。長期運用するなら、レンダラー本体のリリース状況を含めて見る必要があります。
現実的な進め方は、最も複雑な帳票 1 種類を選び、Takumi と Forme の両方で試作して、和文フォント込みの出力・改ページ・生成時間を比較することです。pdfcn は部品を add するだけなので、この検証は数時間から着手できます。ここで問題が出なければ、残りの帳票へ展開する判断ができます。
帳票 PDF の生成方式の選定や、既存アプリへの組み込みで迷っている場合は、要件を整理した段階でご相談ください。chot Inc. は Web サイト制作・フロントエンド開発・AI アプリケーション開発を行っており、React/Next.js での実装検討もお手伝いできます。お問い合わせからお気軽にご連絡ください。


