Converter documentos em Node.js: ferramentas de código aberto
A conversão de documentos é uma necessidade frequente em aplicações Node.js, seja para gerar PDFs a partir de HTML, criar faturas ou exportar relatórios. Felizmente, o ecossistema Node.js oferece várias bibliotecas robustas de código aberto que simplificam essas tarefas. Vamos conhecer algumas das melhores opções disponíveis, com exemplos práticos para ajudar você a escolher a ferramenta certa para o seu projeto.
Estes exemplos renderizam ou geram PDFs; eles não convertem arquivos arbitrários do Word, de
planilhas ou PDF em outros formatos editáveis. Use o Node.js 22.12 ou posterior para os exemplos de
servidor e salve cada um como um arquivo .cjs separado. O exemplo com
jsPDF é executado no navegador.
Bibliotecas de código aberto populares para conversão de documentos
Estas são algumas bibliotecas amplamente usadas:
- Puppeteer: automação do Chrome headless para conversão de HTML para PDF.
- PDFKit: geração de PDFs no servidor com amplas opções de personalização.
- jsPDF: geração de PDFs no cliente, diretamente no navegador.
- wkhtmltopdf: ferramenta de linha de comando arquivada para fluxos de trabalho legados de HTML para PDF.
Vamos nos aprofundar em cada uma delas.
Conversão de HTML para PDF com Puppeteer
O Puppeteer é uma biblioteca poderosa para Node.js que oferece uma API de alto nível para controlar o Chrome (ou Chromium) headless, o que a torna ideal para converter páginas HTML em PDFs. Ela renderiza páginas web com precisão, incluindo CSS e JavaScript.
Exemplo de uso
Instale o Puppeteer, que também baixa um navegador Chrome compatível:
npm install puppeteer@25
Renderize apenas URLs e HTML que você controla. Um serviço em produção que aceita URLs arbitrárias precisa de isolamento de rede e validação de requisições para impedir o acesso a serviços internos.
const puppeteer = require('puppeteer')
async function htmlToPdf(url, outputPath) {
const browser = await puppeteer.launch()
try {
const page = await browser.newPage()
const response = await page.goto(url, { waitUntil: 'networkidle0' })
if (!response || !response.ok()) {
throw new Error(`Page load failed: ${response?.status() ?? 'no HTTP response'}`)
}
await page.pdf({ path: outputPath, format: 'A4' })
} finally {
await browser.close()
}
}
htmlToPdf('https://example.com', 'example.pdf').catch((error) => {
console.error(error.message)
process.exitCode = 1
})
Prós e contras
- Prós: renderização precisa, suporte a CSS e JavaScript modernos, consegue lidar com Single Page Applications (SPAs).
- Contras: maior consumo de recursos por causa do navegador headless, pode ser mais lento que outros métodos.
Gerar PDFs com PDFKit
O PDFKit é uma biblioteca versátil para criar PDFs de forma programática no servidor. Ela permite um controle detalhado sobre o conteúdo e o layout do PDF.
Exemplo de uso
npm install pdfkit@0.17
Aguarde a conclusão do stream de saída para que erros de disco sejam reportados antes de declarar sucesso:
const PDFDocument = require('pdfkit')
const fs = require('fs')
const { pipeline } = require('node:stream/promises')
async function createPdf(outputPath) {
const doc = new PDFDocument()
const writing = pipeline(doc, fs.createWriteStream(outputPath))
try {
doc.fontSize(25).text('Hello, PDFKit!', 100, 100)
doc.fontSize(12).text('This is a sample PDF generated using PDFKit.', 100, 150)
doc.end()
} catch (error) {
doc.destroy(error)
}
await writing
}
createPdf('output.pdf').catch((error) => {
console.error(error.message)
process.exitCode = 1
})
Prós e contras
- Prós: altamente personalizável, leve, bom para gerar PDFs do zero.
- Contras: exige gerenciamento manual do layout, pode ser complexo para designs elaborados.
Geração de PDFs no cliente com jsPDF
O jsPDF permite gerar PDFs diretamente no navegador, muitas vezes em conjunto com o html2canvas, que captura o conteúdo HTML e o converte em uma imagem, que depois é adicionada ao PDF.
Exemplo de uso
<script src="https://cdn.jsdelivr.net/npm/jspdf@4.2.1/dist/jspdf.umd.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/html2canvas@1.4.1/dist/html2canvas.min.js"></script>
<div id="content">Hello, jsPDF!</div>
<button id="download">Download PDF</button>
<p id="status" role="status"></p>
<script>
async function generatePDF() {
const { jsPDF } = window.jspdf
const content = document.getElementById('content')
const canvas = await html2canvas(content)
const imgData = canvas.toDataURL('image/png')
const pdf = new jsPDF()
const width = pdf.internal.pageSize.getWidth() - 20
const height = pdf.internal.pageSize.getHeight() - 20
const scale = Math.min(width / canvas.width, height / canvas.height)
pdf.addImage(imgData, 'PNG', 10, 10, canvas.width * scale, canvas.height * scale)
pdf.save('download.pdf')
}
document.getElementById('download').addEventListener('click', async () => {
const status = document.getElementById('status')
status.textContent = ''
try {
await generatePDF()
} catch {
status.textContent = 'Unable to generate the PDF. Please try again.'
}
})
</script>
Isso encaixa uma captura de tela em uma única página. Conteúdos longos ficam menores, e a imagem resultante não tem texto selecionável nem estrutura de documento para leitores de tela. Use um layout de PDF baseado em texto quando esses recursos forem necessários; o html2canvas também exige imagens da mesma origem ou com CORS habilitado.
Prós e contras
- Prós: não exige processamento no servidor, integração fácil, adequado para aplicações no cliente.
- Contras: controle limitado de estilo e layout em comparação com soluções no servidor, e a renderização pode diferir um pouco do HTML original por causa das limitações do html2canvas.
Conversão avançada com wkhtmltopdf
O wkhtmltopdf converte HTML em PDF usando um motor Qt WebKit antigo. O repositório foi arquivado em janeiro de 2023, e o projeto não recebe mais manutenção. Este exemplo serve apenas para instalações existentes que processam HTML confiável. As orientações de segurança do projeto alertam contra entradas não confiáveis. Use um renderizador com manutenção ativa, como o Puppeteer, em novas aplicações.
Exemplo de uso
const { execFile } = require('node:child_process')
execFile('wkhtmltopdf', ['https://example.com', 'output.pdf'], (error) => {
if (error) {
console.error(`Error: ${error.message}`)
process.exitCode = 1
return
}
console.log('PDF generated successfully')
})
Prós e contras
- Prós: pode preservar fluxos de trabalho em lote existentes construídos em torno do seu motor de renderização mais antigo.
- Contras: exige um binário externo, não tem manutenção nem compatibilidade com navegadores modernos e não deve processar HTML não confiável.
Como escolher a biblioteca certa
Considere estes fatores ao escolher uma biblioteca:
- Complexidade: o Puppeteer oferece suporte a layouts modernos e conteúdo dinâmico. Reserve o wkhtmltopdf para fluxos de trabalho legados e confiáveis.
- Desempenho: o PDFKit é leve e rápido para gerar PDFs simples do zero. Se a velocidade for crítica e a estrutura do seu PDF for relativamente simples, o PDFKit é um forte candidato.
- Ambiente: o jsPDF é ideal para aplicações no cliente em que você quer gerar PDFs diretamente no navegador do usuário.
- Dependências: o wkhtmltopdf exige a instalação de um binário separado, enquanto as outras são bibliotecas puras de Node.js (embora o Puppeteer gerencie seu próprio binário do Chromium/Chrome).
Avalie as necessidades específicas do seu projeto para escolher a melhor opção. Por exemplo, se você precisa gerar faturas com um layout consistente, o PDFKit pode ser uma boa escolha. Se precisa converter em PDF uma página web complexa e com muito JavaScript, o Puppeteer seria mais adequado.
Conversão de documentos da Transloadit
Se você procura uma solução gerenciada, o
serviço de processamento de documentos da Transloadit oferece
recursos robustos de conversão de documentos por meio do Robot /document/convert. Você
pode integrá-lo facilmente às suas aplicações Node.js usando o nosso
node-sdk.