Génération PDF avec PDFKit : factures, rapports et certificats
La génération de PDF est l'une de ces fonctionnalités qui semblent simples jusqu'à ce que vous commenciez à la mettre en œuvre. Des tableaux dynamiques qui débordent correctement des pages, du texte multilingue avec prise en charge du RTL arabe, une numérotation de page appropriée, des en-têtes et pieds de page cohérents sur toutes les pages, des logos intégrés — tout cela nécessite un moteur de mise en page qui gère la complexité pour vous. PDFKit est une bibliothèque de génération PDF Node.js de bas niveau mais puissante qui vous donne un contrôle précis sur chaque élément.
Ce guide couvre les modèles PDFKit pour la génération de PDF de production dans NestJS : modèles de facture, tableaux de données avec pagination, mises en page multicolonnes, polices personnalisées, intégration d'images et diffusion en streaming - jusqu'à l'envoi par courrier électronique du PDF généré en pièce jointe.
Points clés à retenir
- PDFKit génère des PDF par programmation dans Node.js — pas de navigateur, pas de Puppeteer, pas de conversion HTML en PDF
- Mettez toujours le PDF en mémoire tampon jusqu'à son achèvement avant de l'envoyer — ne diffusez pas un PDF incomplet au client
- Intégrez des polices via
registerFont()pour un rendu multiplateforme cohérent - ne comptez jamais sur les polices système- Les documents de plusieurs pages nécessitent une détection manuelle des sauts de page : vérifiez la position
doc.ypar rapport àdoc.page.height- Pour le texte arabe et RTL, utilisez une police arabe appropriée (Noto Sans Arabic) et gérez manuellement la direction du texte.
- Diffusez des PDF sur AWS S3 et renvoyez une URL pré-signée — ne transmettez pas de gros tampons via votre API
- Utilisez
doc.pipe(fs.createWriteStream())pour les tests ;doc.pipe(res)pour le streaming HTTP ; tampon pour les pièces jointes des e-mails- Ajouter des métadonnées PDF/A pour la conformité de l'archivage : champs
Title,Author,Creator,Producer
##Installation
pnpm add pdfkit
pnpm add -D @types/pdfkit
Pour la prise en charge des images (PNG, JPEG) et des sous-ensembles de polices, aucun package supplémentaire n'est nécessaire : PDFKit les gère de manière native.
Structure de base des factures
// src/modules/billing/pdf/invoice.generator.ts
import PDFDocument from 'pdfkit';
import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import * as fs from 'fs';
import * as path from 'path';
interface InvoiceData {
invoiceNumber: string;
date: Date;
dueDate: Date;
customer: {
name: string;
email: string;
address: string;
city: string;
country: string;
};
items: Array<{
description: string;
quantity: number;
unitPrice: number;
total: number;
}>;
subtotal: number;
tax: number;
total: number;
currency: string;
notes?: string;
}
@Injectable()
export class InvoiceGenerator {
private readonly primaryColor = '#0f172a';
private readonly accentColor = '#f59e0b';
private readonly mutedColor = '#64748b';
private readonly borderColor = '#e2e8f0';
constructor(private config: ConfigService) {}
async generate(data: InvoiceData): Promise<Buffer> {
return new Promise((resolve, reject) => {
const buffers: Buffer[] = [];
const doc = new PDFDocument({
size: 'A4',
margin: 50,
info: {
Title: `Invoice ${data.invoiceNumber}`,
Author: 'ECOSIRE Private Limited',
Creator: 'ECOSIRE Billing System',
Producer: 'PDFKit',
},
});
// Collect chunks into buffer (do not stream incomplete PDFs)
doc.on('data', (chunk: Buffer) => buffers.push(chunk));
doc.on('end', () => resolve(Buffer.concat(buffers)));
doc.on('error', reject);
this.renderHeader(doc, data);
this.renderCustomerSection(doc, data);
this.renderItemsTable(doc, data);
this.renderTotals(doc, data);
if (data.notes) this.renderNotes(doc, data.notes);
this.renderFooter(doc, data);
doc.end();
});
}
private renderHeader(doc: PDFKit.PDFDocument, data: InvoiceData): void {
// Company logo
const logoPath = path.join(process.cwd(), 'public', 'logo-dark.png');
if (fs.existsSync(logoPath)) {
doc.image(logoPath, 50, 45, { width: 120 });
} else {
doc
.fontSize(18)
.fillColor(this.primaryColor)
.font('Helvetica-Bold')
.text('ECOSIRE', 50, 50);
}
// Invoice label and number
doc
.fontSize(28)
.fillColor(this.accentColor)
.font('Helvetica-Bold')
.text('INVOICE', 0, 50, { align: 'right' });
doc
.fontSize(10)
.fillColor(this.mutedColor)
.font('Helvetica')
.text(`#${data.invoiceNumber}`, 0, 82, { align: 'right' });
// Divider line
doc
.moveTo(50, 110)
.lineTo(545, 110)
.lineWidth(1)
.strokeColor(this.borderColor)
.stroke();
doc.moveDown(2);
}
private renderCustomerSection(doc: PDFKit.PDFDocument, data: InvoiceData): void {
const startY = 130;
// Billed To
doc
.fontSize(8)
.fillColor(this.mutedColor)
.font('Helvetica-Bold')
.text('BILLED TO', 50, startY)
.fontSize(11)
.fillColor(this.primaryColor)
.text(data.customer.name, 50, startY + 16)
.fontSize(9)
.fillColor(this.mutedColor)
.font('Helvetica')
.text(data.customer.email, 50, startY + 32)
.text(data.customer.address, 50, startY + 46)
.text(`${data.customer.city}, ${data.customer.country}`, 50, startY + 60);
// Invoice dates (right column)
const dateRows = [
['Invoice Date:', this.formatDate(data.date)],
['Due Date:', this.formatDate(data.dueDate)],
['Currency:', data.currency],
];
let dateY = startY;
for (const [label, value] of dateRows) {
doc
.fontSize(9)
.fillColor(this.mutedColor)
.font('Helvetica')
.text(label, 350, dateY, { width: 90 });
doc
.fontSize(9)
.fillColor(this.primaryColor)
.font('Helvetica-Bold')
.text(value, 445, dateY, { width: 100, align: 'right' });
dateY += 18;
}
doc.moveDown(5);
}
private renderItemsTable(doc: PDFKit.PDFDocument, data: InvoiceData): void {
const tableTop = 265;
const colWidths = { desc: 230, qty: 60, unitPrice: 90, total: 90 };
const startX = 50;
// Table header background
doc
.rect(startX, tableTop, 495, 22)
.fillColor(this.primaryColor)
.fill();
// Header text
doc
.fontSize(9)
.fillColor('#ffffff')
.font('Helvetica-Bold')
.text('DESCRIPTION', startX + 8, tableTop + 6, { width: colWidths.desc })
.text('QTY', startX + colWidths.desc + 8, tableTop + 6, { width: colWidths.qty, align: 'center' })
.text('UNIT PRICE', startX + colWidths.desc + colWidths.qty + 8, tableTop + 6, { width: colWidths.unitPrice, align: 'right' })
.text('TOTAL', startX + colWidths.desc + colWidths.qty + colWidths.unitPrice + 8, tableTop + 6, { width: colWidths.total, align: 'right' });
let rowY = tableTop + 28;
const fmt = new Intl.NumberFormat('en-US', {
style: 'currency',
currency: data.currency,
});
for (const [index, item] of data.items.entries()) {
// Alternating row background
if (index % 2 === 0) {
doc
.rect(startX, rowY - 4, 495, 24)
.fillColor('#f8fafc')
.fill();
}
doc
.fontSize(9)
.fillColor(this.primaryColor)
.font('Helvetica')
.text(item.description, startX + 8, rowY, { width: colWidths.desc })
.text(String(item.quantity), startX + colWidths.desc + 8, rowY, { width: colWidths.qty, align: 'center' })
.text(fmt.format(item.unitPrice), startX + colWidths.desc + colWidths.qty + 8, rowY, { width: colWidths.unitPrice, align: 'right' })
.text(fmt.format(item.total), startX + colWidths.desc + colWidths.qty + colWidths.unitPrice + 8, rowY, { width: colWidths.total, align: 'right' });
rowY += 24;
// Page break check
if (rowY > doc.page.height - 150) {
doc.addPage();
rowY = 50;
}
}
// Table bottom border
doc
.moveTo(startX, rowY + 4)
.lineTo(545, rowY + 4)
.lineWidth(1)
.strokeColor(this.borderColor)
.stroke();
doc.y = rowY + 20;
}
private renderTotals(doc: PDFKit.PDFDocument, data: InvoiceData): void {
const fmt = new Intl.NumberFormat('en-US', {
style: 'currency',
currency: data.currency,
});
const totalsX = 350;
let currentY = doc.y + 10;
const rows = [
['Subtotal', fmt.format(data.subtotal), false],
[`Tax (${((data.tax / data.subtotal) * 100).toFixed(0)}%)`, fmt.format(data.tax), false],
['Total Due', fmt.format(data.total), true],
];
for (const [label, value, isTotal] of rows) {
if (isTotal) {
doc
.rect(totalsX, currentY - 4, 195, 28)
.fillColor(this.accentColor)
.fill();
doc
.fontSize(11)
.fillColor('#000000')
.font('Helvetica-Bold')
.text(label as string, totalsX + 8, currentY + 2, { width: 90 })
.text(value as string, totalsX + 98, currentY + 2, { width: 89, align: 'right' });
} else {
doc
.fontSize(9)
.fillColor(this.mutedColor)
.font('Helvetica')
.text(label as string, totalsX + 8, currentY, { width: 90 })
.fillColor(this.primaryColor)
.text(value as string, totalsX + 98, currentY, { width: 89, align: 'right' });
}
currentY += 28;
}
doc.y = currentY + 10;
}
private renderNotes(doc: PDFKit.PDFDocument, notes: string): void {
doc.moveDown(2);
doc
.fontSize(9)
.fillColor(this.mutedColor)
.font('Helvetica-Bold')
.text('NOTES', 50, doc.y);
doc
.fontSize(9)
.fillColor(this.primaryColor)
.font('Helvetica')
.text(notes, 50, doc.y + 12, { width: 495 });
}
private renderFooter(doc: PDFKit.PDFDocument, _data: InvoiceData): void {
const footerY = doc.page.height - 60;
doc
.moveTo(50, footerY - 10)
.lineTo(545, footerY - 10)
.lineWidth(1)
.strokeColor(this.borderColor)
.stroke();
doc
.fontSize(8)
.fillColor(this.mutedColor)
.font('Helvetica')
.text(
'ECOSIRE Private Limited | [email protected] | ecosire.com',
50,
footerY,
{ align: 'center', width: 495 }
);
}
private formatDate(date: Date): string {
return new Intl.DateTimeFormat('en-US', {
year: 'numeric', month: 'long', day: 'numeric',
}).format(date);
}
}
Intégration du contrôleur NestJS
// src/modules/billing/billing.controller.ts
@Controller('billing')
export class BillingController {
constructor(
private readonly billingService: BillingService,
private readonly invoiceGenerator: InvoiceGenerator,
private readonly emailService: EmailService,
) {}
@Get('invoices/:id/pdf')
async downloadInvoice(
@Param('id') id: string,
@Req() req: AuthenticatedRequest,
@Res() res: Response
): Promise<void> {
const invoice = await this.billingService.getInvoice(id, req.user.organizationId);
if (!invoice) {
throw new NotFoundException('Invoice not found');
}
const pdfBuffer = await this.invoiceGenerator.generate({
invoiceNumber: invoice.number,
date: invoice.createdAt,
dueDate: invoice.dueDate,
customer: {
name: req.user.name,
email: req.user.email,
address: invoice.billingAddress,
city: invoice.billingCity,
country: invoice.billingCountry,
},
items: invoice.lineItems,
subtotal: invoice.subtotal,
tax: invoice.tax,
total: invoice.total,
currency: invoice.currency,
});
res.set({
'Content-Type': 'application/pdf',
'Content-Disposition': `attachment; filename="invoice-${invoice.number}.pdf"`,
'Content-Length': pdfBuffer.length,
'Cache-Control': 'private, no-cache',
});
res.send(pdfBuffer);
}
@Post('invoices/:id/email')
async emailInvoice(
@Param('id') id: string,
@Req() req: AuthenticatedRequest
) {
const invoice = await this.billingService.getInvoice(id, req.user.organizationId);
const pdfBuffer = await this.invoiceGenerator.generate({
invoiceNumber: invoice.number,
// ... populate from invoice data
} as InvoiceData);
// Non-blocking email send
this.emailService.sendInvoiceEmail(
req.user.email,
req.user.name,
invoice.number,
pdfBuffer
).catch((err) =>
this.logger.warn(`Invoice email failed: ${err.message}`)
);
return { message: 'Invoice sent to ' + req.user.email };
}
}
Rapport multipage avec numéros de page
// For reports spanning multiple pages
async generateReport(data: ReportData): Promise<Buffer> {
return new Promise((resolve, reject) => {
const buffers: Buffer[] = [];
const doc = new PDFDocument({ size: 'A4', margin: 50 });
doc.on('data', (chunk: Buffer) => buffers.push(chunk));
doc.on('end', () => resolve(Buffer.concat(buffers)));
doc.on('error', reject);
const pageCount = Math.ceil(data.rows.length / 30); // 30 rows per page
let currentPage = 0;
// Add page numbers to every page on finalize
doc.on('pageAdded', () => {
currentPage++;
doc
.fontSize(8)
.fillColor('#94a3b8')
.text(
`Page ${currentPage}`,
0,
doc.page.height - 30,
{ align: 'center', width: doc.page.width }
);
});
// Render content
this.renderReportHeader(doc, data);
let rowIndex = 0;
for (const row of data.rows) {
if (doc.y > doc.page.height - 100) {
doc.addPage(); // Triggers 'pageAdded' for footer
this.renderReportHeader(doc, data); // Re-render header on new page
}
this.renderTableRow(doc, row, rowIndex++);
}
doc.end();
});
}
Diffusion vers S3
Pour les rapports volumineux, diffusez directement vers S3 plutôt que de mettre en mémoire tampon :
import { PassThrough } from 'stream';
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
async function generateAndUploadToS3(
invoiceData: InvoiceData,
s3: S3Client,
bucket: string,
key: string
): Promise<string> {
const passThrough = new PassThrough();
const doc = new PDFDocument({ size: 'A4', margin: 50 });
doc.pipe(passThrough);
// Render invoice content
renderInvoice(doc, invoiceData);
doc.end();
// Upload stream to S3
await s3.send(new PutObjectCommand({
Bucket: bucket,
Key: key,
Body: passThrough,
ContentType: 'application/pdf',
Metadata: {
'invoice-number': invoiceData.invoiceNumber,
},
}));
return `s3://${bucket}/${key}`;
}
Modèle de certificat
async generateCertificate(data: CertificateData): Promise<Buffer> {
return new Promise((resolve, reject) => {
const buffers: Buffer[] = [];
const doc = new PDFDocument({
size: [792, 612], // Letter landscape
margin: 60,
layout: 'landscape',
});
doc.on('data', (chunk: Buffer) => buffers.push(chunk));
doc.on('end', () => resolve(Buffer.concat(buffers)));
doc.on('error', reject);
// Background
doc.rect(0, 0, 792, 612).fillColor('#fefce8').fill();
// Gold border (double line)
doc
.rect(20, 20, 752, 572)
.lineWidth(3)
.strokeColor('#f59e0b')
.stroke();
doc
.rect(28, 28, 736, 556)
.lineWidth(1)
.strokeColor('#f59e0b')
.stroke();
// Title
doc
.fontSize(36)
.fillColor('#0f172a')
.font('Helvetica-Bold')
.text('CERTIFICATE OF COMPLETION', 60, 100, { align: 'center' });
// Recipient name
doc
.fontSize(28)
.fillColor('#f59e0b')
.text(data.recipientName, 60, 200, { align: 'center' });
// Course name
doc
.fontSize(16)
.fillColor('#0f172a')
.font('Helvetica')
.text(`has successfully completed`, 60, 260, { align: 'center' })
.fontSize(20)
.font('Helvetica-Bold')
.text(data.courseName, 60, 290, { align: 'center' });
// Date and signature
doc
.fontSize(11)
.fillColor('#64748b')
.font('Helvetica')
.text(`Issued on ${this.formatDate(data.issuedDate)}`, 60, 400, { align: 'center' });
doc.end();
});
}
Questions fréquemment posées
PDFKit vs Puppeteer pour la génération de PDF : lequel dois-je utiliser ?
PDFKit pour documents structurés : factures, rapports, attestations, lettres. Il est rapide (pas de démarrage du navigateur), utilise un minimum de mémoire et offre un contrôle parfait sur la mise en page. Puppeteer pour la conversion HTML en PDF : idéal lorsque vous disposez déjà d'un modèle HTML et que vous avez besoin de le rendre tel quel, y compris des CSS complexes, des polices Web et du JavaScript dynamique. Puppeteer est 5 à 10 fois plus lent et nécessite un processus Chrome sans tête, mais gère mieux les mises en page de l'ère Web. Pour les factures et les documents commerciaux, PDFKit est le bon choix.
Comment gérer les sauts de page pour le contenu dynamique dans PDFKit ?
PDFKit ne pagine pas automatiquement — vous devez vérifier doc.y par rapport à doc.page.height - margin avant de restituer chaque élément. Le modèle : if (doc.y > doc.page.height - minSpaceNeeded) { doc.addPage(); renderPageHeader(doc); }. Pour les lignes du tableau, calculez l'espace minimum nécessaire pour une ligne et vérifiez avant chaque ligne. Pour un texte multiligne, estimez la hauteur comme fontSize * lineCount * 1.2.
Comment intégrer des polices personnalisées dans PDFKit ?
Enregistrez les polices avec doc.registerFont('FontName', '/path/to/font.ttf') avant de les utiliser. Appelez cela dans votre constructeur de service ou dans une fonction de configuration. PDFKit est livré avec les 14 polices PDF standard (Helvetica, Times, Courier et leurs variantes gras/italique) — celles-ci n'ont pas besoin d'être enregistrées. Pour la prise en charge d'Unicode (arabe, chinois, japonais), vous devez enregistrer une police TTF/OTF compatible Unicode ; les polices PDF standard ne couvrent que les caractères latins.
Comment générer des PDF pour l'arabe ou d'autres langues RTL ?
PDFKit prend en charge Unicode mais ne gère pas nativement la réorganisation bidirectionnelle du texte. Pour l’arabe, enregistrez la police Noto Sans Arabic ou Amiri. Utilisez une bibliothèque d'algorithmes bidi (comme bidi-js) pour réorganiser le texte avant de le transmettre à PDFKit. Inversez manuellement la mise en page pour les documents RTL (texte aligné à droite, colonnes de tableau en miroir). Testez minutieusement : la génération de PDF en arabe nécessite une gestion minutieuse de la jointure du texte, des signes diacritiques et de la direction des nombres.
Comment ajouter des signatures numériques ou la conformité PDF/A ?
PDFKit prend en charge les métadonnées PDF de base pour l'archivage (Titre, Auteur, Sujet, Mots-clés) via l'option info. Pour les signatures numériques, utilisez la bibliothèque node-signpdf avec PDFKit : elle modifie le flux PDF pour intégrer une signature PKCS#7. Pour la conformité PDF/A (archivage à long terme), assurez-vous que les polices sont intégrées, qu'elles ne sont pas transparentes et que les définitions d'espace colorimétrique sont appropriées. PDFKit v0.13+ a amélioré la prise en charge de ces fonctionnalités, mais des exigences de conformité complexes peuvent bénéficier d'une bibliothèque dédiée comme pdf-lib.
Prochaines étapes
PDFKit permet la génération professionnelle et programmatique de PDF directement dans votre backend Node.js — pas de surcharge de navigateur, pas de services externes, pas de tarification par page. Les factures, rapports, certificats et relevés deviennent des fonctionnalités de premier ordre de votre API.
ECOSIRE implémente la génération de factures PDF, l'envoi automatisé d'e-mails et l'archivage S3 dans le cadre du pipeline de facturation complet sur chaque projet NestJS. Découvrez nos services d'ingénierie back-end pour découvrir comment nous construisons des systèmes de facturation et de reporting de qualité production.
Rédigé par
ECOSIRE Research and Development Team
Création de produits numériques de niveau entreprise chez ECOSIRE. Partage d'analyses sur les intégrations Odoo, l'automatisation e-commerce et les solutions d'entreprise propulsées par l'IA.