PDFKit para JavaScript (Node.js): guia completo com exemplos

Introdução ao PDFKit

PDFKit é uma biblioteca poderosa e flexível para gerar documentos PDF no lado do servidor usando JavaScript (Node.js). Ela oferece aos desenvolvedores controle total sobre o processo de criação de PDF: desde documentos de texto simples até relatórios complexos de várias páginas com tabelas, imagens, gráficos e elementos interativos. O PDFKit não requer a instalação de dependências adicionais, como PhantomJS ou Puppeteer, e funciona exclusivamente com JavaScript puro, tornando-o a escolha ideal para aplicações de servidor de alta demanda.

Por que usar esta biblioteca? No desenvolvimento web moderno, surge frequentemente a necessidade de gerar documentos PDF programaticamente: faturas, notas fiscais, relatórios, certificados, contratos. O PDFKit resolve esse problema de forma elegante e eficiente. Ao contrário dos conversores de HTML para PDF, que podem ser lentos e imprevisíveis, o PDFKit oferece acesso direto ao modelo PDF: você mesmo define as coordenadas de cada elemento, gerencia fontes, cores e layout das páginas. Isso é especialmente importante quando é necessário posicionar elementos com precisão ou trabalhar com formatos não padronizados.

A biblioteca é ativamente mantida pela comunidade, possui documentação extensa e é usada em produção por milhares de empresas em todo o mundo. O PDFKit suporta todos os principais recursos do formato PDF: incorporação de fontes (incluindo acentos e caracteres especiais do português), trabalho com imagens (JPEG, PNG, SVG), criação de anotações, hiperlinks, marcadores, além de criptografia de documentos. Graças à arquitetura modular e à capacidade de gravação em stream, o PDFKit é perfeito tanto para criar documentos pequenos quanto arquivos PDF de vários gigabytes.

Instalação do PDFKit

O PDFKit é distribuído através do gerenciador de pacotes npm. A instalação é feita com o comando padrão:

npm install pdfkit

Para trabalhar com TypeScript, pode ser necessário instalar tipos adicionais:

npm install pdfkit @types/pdfkit

Se você usa Yarn:

yarn add pdfkit

Após a instalação, a biblioteca está pronta para uso. Nenhuma dependência adicional ou requisito de sistema é necessário — tudo funciona "pronto para uso" em qualquer plataforma que suporte Node.js (Windows, macOS, Linux).

Início rápido: exemplo mínimo funcional

Crie um arquivo hello-pdf.js e adicione o seguinte código:

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

// Cria um novo documento PDF
const doc = new PDFDocument();

// Define onde salvar o resultado
doc.pipe(fs.createWriteStream('hello.pdf'));

// Adiciona texto
doc.fontSize(25)
   .text('Olá, mundo!', 100, 100);

// Finaliza o documento
doc.end();

console.log('PDF criado: hello.pdf');

Execute o script:

node hello-pdf.js

No diretório atual, aparecerá o arquivo hello.pdf com o texto "Olá, mundo!". Este exemplo demonstra o princípio básico de trabalho com PDFKit: criar um documento, adicionar conteúdo e salvar o resultado.

Métodos e classes principais do PDFKit

O PDFKit fornece uma API rica para trabalhar com documentos PDF. Vamos explorar os principais métodos que serão úteis no desenvolvimento do dia a dia.

1. new PDFDocument(options) — Construtor do documento

Assinatura: new PDFDocument([options])

Descrição: Cria uma nova instância de documento PDF. O parâmetro options é um objeto que permite definir o tamanho da página, margens, orientação, metadados e outras configurações.

const doc = new PDFDocument({
  size: 'A4',              // Tamanho da página (A4, Letter, Legal, etc.)
  layout: 'portrait',      // Orientação: 'portrait' ou 'landscape'
  margins: {               // Margens