Managing PDFs with Node.js and pdf-lib

Why PDF Management Matters in Modern Web Applications

Modern web applications frequently need to generate, modify, or process PDF documents. Whether you're building invoice generators, report systems, or document management platforms, the ability to work with PDFs programmatically is essential. The pdf-lib library provides a powerful, pure JavaScript solution for PDF manipulation that works seamlessly in both Node.js environments and modern web browsers.

Unlike server-side solutions that require external binaries or paid services, pdf-lib runs entirely in JavaScript, making it ideal for serverless environments and edge deployments. The library supports the full PDF specification while maintaining a clean, Promise-based API that feels natural in modern asynchronous codebases. This approach aligns perfectly with modern web development practices that prioritize flexibility and scalability.

For businesses automating document workflows, integrating PDF generation into your web application can significantly reduce manual processing and improve accuracy across your operations.

Getting Started with pdf-lib

The pdf-lib library has become the go-to solution for JavaScript developers who need to work with PDF documents. Installing pdf-lib is straightforward regardless of your package manager preference. The library works in Node.js 14 and above, as well as all modern browsers including Chrome, Firefox, Safari, and Edge.

Installation

npm install pdf-lib
# or
yarn add pdf-lib
# or
pnpm add pdf-lib

Basic Import

const { PDFDocument, rgb, StandardFonts } = require('pdf-lib');
// or for ES modules
import { PDFDocument, rgb, StandardFonts } from 'pdf-lib';

At the heart of pdf-lib lies the PDFDocument class, which serves as your entry point for all PDF operations. This class represents a PDF document in memory and provides methods for creating new documents, loading existing ones, and performing modifications. The async nature of most operations means pdf-lib integrates naturally with modern JavaScript patterns including async/await and Promise-based APIs, making it an excellent choice for Node.js development.

Creating PDF Documents from Scratch

Building a PDF from scratch with pdf-lib gives you complete control over the document structure and content. This approach works well for generating invoices, certificates, reports, or any document where you control the entire content. The library handles the complexity of the PDF specification while you focus on the document's content and layout.

Basic Document Creation

Creating a new PDF document begins with instantiating a PDFDocument and adding pages as needed. Each page has configurable dimensions, and you can add content using the draw methods available on page objects.

const { PDFDocument, rgb, StandardFonts } = require('pdf-lib');

async function createInvoice() {
 const pdfDoc = await PDFDocument.create();
 const page = pdfDoc.addPage([612, 792]); // Letter size
 
 const { width, height } = page.getSize();
 const font = await pdfDoc.embedFont(StandardFonts.Helvetica);
 
 page.drawText('Invoice', {
 x: 50,
 y: height - 100,
 size: 24,
 font: font,
 color: rgb(0, 0, 0)
 });
 
 return await pdfDoc.save();
}

Working with Page Dimensions

PDF pages can be created with custom dimensions or using standard page sizes. The library supports precise positioning through a coordinate system where x increases to the right and y increases upward. Understanding this system is crucial for creating well-laid-out documents. You can retrieve page dimensions at any time and dynamically position content based on those dimensions.

This level of programmatic control makes pdf-lib particularly valuable for custom web applications that need to generate standardized documents at scale.

Adding Rich Content to PDFs

Beyond simple text, pdf-lib supports embedding images, custom fonts, and vector graphics. This capability enables you to create branded documents with logos, styled text with custom typography, and professional-looking reports that match your application's design system.

Embedding Images

Images can be embedded in PNG or JPEG format and positioned anywhere on a page. The library handles image compression and optimization automatically, keeping file sizes reasonable even when embedding multiple images.

async function addLogoToPdf() {
 const pdfDoc = await PDFDocument.create();
 const page = pdfDoc.addPage([500, 500]);
 
 const imageBytes = fs.readFileSync('logo.png');
 const image = await pdfDoc.embedPng(imageBytes);
 const imageDims = image.scale(0.5);
 
 page.drawImage(image, {
 x: 50,
 y: page.getHeight() - imageDims.height - 50,
 width: imageDims.width,
 height: imageDims.height
 });
}

Custom Fonts

While pdf-lib includes several standard fonts (Helvetica, Times, Courier), most professional documents require custom typography. The library supports embedding TrueType and OpenType fonts, giving you access to your complete typeface library.

async function useCustomFont() {
 const pdfDoc = await PDFDocument.create();
 const page = pdfDoc.addPage();
 
 const fontBytes = fs.readFileSync('fonts/Inter-Bold.ttf');
 const customFont = await pdfDoc.embedFont(fontBytes);
 
 page.drawText('Styled Heading', {
 x: 50,
 y: 400,
 size: 32,
 font: customFont,
 color: rgb(0.1, 0.3, 0.6)
 });
}

When building document generation systems, consistent branding through custom fonts and logos helps maintain a professional appearance across all generated documents, reinforcing your brand identity in every web application.

Modifying Existing PDFs

Many PDF workflows involve modifying existing documents rather than creating them from scratch. Pdf-lib excels at this use case, allowing you to load existing PDFs, make targeted modifications, and save the result. This capability powers features like document merging, watermark application, and form filling.

Loading and Editing PDFs

Loading an existing PDF is as simple as calling PDFDocument.load with the PDF bytes. Once loaded, you can access any page, add new content, or modify existing elements. The library maintains the original document structure while allowing your changes to be seamlessly integrated.

async function addWatermarkToPdf(inputPath, outputPath) {
 const existingPdfBytes = fs.readFileSync(inputPath);
 const pdfDoc = await PDFDocument.load(existingPdfBytes);
 const font = await pdfDoc.embedFont(StandardFonts.HelveticaBold);
 
 const pages = pdfDoc.getPages();
 for (const page of pages) {
 const { width, height } = page.getSize();
 
 page.drawText('CONFIDENTIAL', {
 x: width / 2 - 100,
 y: height / 2,
 size: 48,
 font: font,
 color: rgb(0.8, 0.2, 0.2),
 opacity: 0.3,
 rotate: 45
 });
 }
 
 fs.writeFileSync(outputPath, await pdfDoc.save());
}

Removing and Rearranging Pages

Pdf-lib provides methods for removing pages, rearranging page order, and duplicating pages from one document to another. These operations are essential for document assembly workflows where you combine content from multiple sources, a common requirement in enterprise web development projects.

Merging and Splitting PDFs

Document assembly is a common requirement in business applications. Pdf-lib makes it straightforward to combine multiple PDFs into a single document or extract specific pages from a source PDF. The copyPages method is the key to these operations, allowing you to selectively include pages from any loaded PDF.

Combining Multiple PDFs

Merging PDFs involves creating a new document, loading each source PDF, and copying pages into the new document. This approach gives you complete control over the page order and allows you to selectively include only the pages you need.

async function mergeInvoices(pdfPaths, outputPath) {
 const mergedPdf = await PDFDocument.create();
 
 for (const pdfPath of pdfPaths) {
 const pdfBytes = fs.readFileSync(pdfPath);
 const sourcePdf = await PDFDocument.load(pdfBytes);
 const pageIndices = sourcePdf.getPageIndices();
 const copiedPages = await mergedPdf.copyPages(sourcePdf, pageIndices);
 
 copiedPages.forEach((page) => mergedPdf.addPage(page));
 }
 
 fs.writeFileSync(outputPath, await mergedPdf.save());
}

Extracting Pages from PDFs

Splitting a PDF into individual documents or smaller batches follows a similar pattern. You load the source document, create a new document for each page or page range, and save each document separately.

Best Practice: Use copyPages() to efficiently transfer pages between documents without duplicating content in memory.

For organizations managing large document repositories, these merging and splitting capabilities form the foundation of automated document workflows that can significantly reduce manual processing time.

Advanced PDF Features

Interactive Forms

Pdf-lib can create and fill PDF form fields including text fields, checkboxes, and dropdowns. This capability is valuable for generating pre-filled documents, creating dynamic templates, or processing form data programmatically.

async function createForm() {
 const pdfDoc = await PDFDocument.create();
 const page = pdfDoc.addPage();
 const form = pdfDoc.getForm();
 
 const nameField = form.createTextField('fullName');
 nameField.setText('Enter your name');
 nameField.addToPage(page, { x: 50, y: 600 });
 
 const agreeField = form.createCheckBox('agree');
 agreeField.addToPage(page, { x: 50, y: 550 });
 
 const options = ['Option 1', 'Option 2', 'Option 3'];
 const selectField = form.createDropdown('selection');
 selectField.addOptions(options);
 selectField.addToPage(page, { x: 50, y: 500 });
}

Document Security

Protecting sensitive documents is crucial in many applications. Pdf-lib supports encryption with user and owner passwords, allowing you to control who can open, print, copy, or modify documents.

async function createSecurePdf() {
 const pdfDoc = await PDFDocument.create();
 const page = pdfDoc.addPage();
 page.drawText('Sensitive Document', { x: 50, y: 700 });
 
 pdfDoc.encrypt({
 userPassword: 'user123',
 ownerPassword: 'owner456',
 permissions: {
 printing: 'lowResolution',
 modifying: false,
 copying: false,
 annotating: false
 }
 });
 
 return await pdfDoc.save();
}

Implementing proper document security is essential for web applications that handle sensitive data, ensuring compliance with privacy requirements and protecting confidential information.

Performance and Best Practices

Memory Management

PDFDocument instances hold the entire document in memory, which works well for most use cases but requires attention when dealing with very large documents or high-volume generation. Consider streaming approaches for extremely large documents and ensure proper cleanup of document instances when they're no longer needed.

Error Handling

All significant operations in pdf-lib are asynchronous, following the Promise-based pattern. Always wrap PDF operations in try-catch blocks to handle potential errors gracefully.

async function safePdfOperation(pdfBytes) {
 try {
 const pdfDoc = await PDFDocument.load(pdfBytes);
 return await pdfDoc.save();
 } catch (error) {
 console.error('PDF operation failed:', error);
 throw new Error('Failed to process PDF document');
 }
}

Next.js Integration

When using pdf-lib with Next.js, consider whether your PDF operations should run on the server or client:

• Server-side: Use API routes for authenticated operations or when document templates include sensitive data
• Client-side: Offload work to browsers for high-volume, public scenarios
• Consider edge compatibility when using specific features

Key Recommendations

1. Always wrap PDF operations in try-catch blocks
2. Reuse font and image objects when possible
3. Consider document size when embedding images
4. Use streaming for very large document sets
5. Test with realistic document sizes during development
6. Consider server vs client execution based on your use case

For high-volume document generation, proper error handling and memory management become critical factors in maintaining application performance.

Conclusion

The pdf-lib library provides a comprehensive solution for PDF manipulation in JavaScript applications. From simple document creation to complex multi-PDF operations, the library offers the features you need while maintaining a clean, modern API. Whether you're building invoice systems, report generators, or document management platforms, pdf-lib fits naturally into your Node.js and Next.js workflows.

Start with basic document creation, then explore merging, forms, and security features as your requirements grow. The library's consistent API and excellent documentation make it accessible for developers at any experience level. With the patterns and practices outlined in this guide, you're well-equipped to implement robust PDF handling in your web applications.

Need help implementing PDF solutions in your project? Our team specializes in building document generation systems and custom web applications tailored to your business needs. We can help you design and implement efficient PDF workflows that integrate seamlessly with your existing systems.

Sources

1. Honeybadger: Managing PDFs in Node.js with pdf-lib - Comprehensive tutorial covering all major pdf-lib features from basic creation to advanced security
2. Generalist Programmer: pdf-lib npm Package Guide - Installation, TypeScript support, and best practices documentation