PDFKit para JavaScript (Node.js): guía completa con ejemplos

Introducción a PDFKit

PDFKit es una librería potente y flexible para generar documentos PDF del lado del servidor usando JavaScript (Node.js). Ofrece a los desarrolladores control total sobre el proceso de creación de PDF: desde documentos de texto simples hasta informes complejos de varias páginas con tablas, imágenes, gráficos y elementos interactivos. PDFKit no requiere dependencias adicionales como PhantomJS o Puppeteer, y funciona exclusivamente con JavaScript puro, lo que lo convierte en una opción ideal para aplicaciones de servidor con alta carga.

¿Para qué sirve esta librería? En el desarrollo web moderno, a menudo es necesario generar documentos PDF de forma programática: facturas, albaranes, informes, certificados, contratos. PDFKit resuelve esta tarea de manera elegante y eficiente. A diferencia de los conversores HTML a PDF, que pueden ser lentos e impredecibles, PDFKit te da acceso directo al modelo PDF: tú defines las coordenadas de cada elemento, gestionas fuentes, colores y la composición de las páginas. Esto es especialmente importante cuando se requiere un posicionamiento preciso de los elementos o trabajar con formatos no estándar.

La librería cuenta con el respaldo activo de la comunidad, tiene una documentación extensa y es utilizada en entornos de producción por miles de empresas en todo el mundo. PDFKit admite todas las funciones principales del formato PDF: incrustación de fuentes (incluyendo caracteres especiales), trabajo con imágenes (JPEG, PNG, SVG), creación de anotaciones, hipervínculos, marcadores, así como cifrado de documentos. Gracias a su arquitectura modular y la capacidad de escritura en flujo, PDFKit es ideal tanto para crear documentos pequeños como archivos PDF de varios gigabytes.

Instalación de PDFKit

PDFKit se distribuye a través del gestor de paquetes npm. La instalación se realiza con el comando estándar:

npm install pdfkit

Para trabajar con TypeScript, puede ser necesario instalar tipos adicionales:

npm install pdfkit @types/pdfkit

Si usas Yarn:

yarn add pdfkit

Una vez instalada, la librería está lista para usar. No se requieren dependencias adicionales ni requisitos del sistema: todo funciona "de fábrica" en cualquier plataforma compatible con Node.js (Windows, macOS, Linux).

Inicio rápido: ejemplo mínimo funcional

Crea un archivo hola-pdf.js y añade el siguiente código:

const PDFDocument = require('pdfkit');
const fs = require('fs');

// Creamos un nuevo documento PDF
const doc = new PDFDocument();

// Indicamos dónde guardar el resultado
doc.pipe(fs.createWriteStream('hola.pdf'));

// Añadimos texto
doc.fontSize(25)
   .text('¡Hola, mundo!', 100, 100);

// Finalizamos el documento
doc.end();

console.log('PDF creado: hola.pdf');

Ejecuta el script:

node hola-pdf.js

En el directorio actual aparecerá un archivo hola.pdf con el texto "¡Hola, mundo!". Este ejemplo demuestra el principio básico de funcionamiento de PDFKit: crear un documento, añadir contenido y guardar el resultado.

Métodos y clases principales de PDFKit

PDFKit proporciona una API rica para trabajar con documentos PDF. Veamos los métodos principales que te serán útiles en el desarrollo diario.

1. new PDFDocument(options) — Constructor del documento

Firma: new PDFDocument([options])

Descripción: Crea una nueva instancia de un documento PDF. El parámetro options es un objeto que permite definir el tamaño de página, márgenes, orientación, metadatos y otras configuraciones.

const doc = new PDFDocument({
  size: 'A4',              // Tamaño de página (A4, Letter, Legal, etc.)
  layout: 'portrait',      // Orientación: 'portrait' o 'landscape'
  margins: {               // Márgenes