DEV Community: John Pagley

How to Programmatically Fill a PDF Form with Raw JavaScript (The Easy Way)

John Pagley — Mon, 22 Dec 2025 15:16:32 +0000

Programmatically filling PDF forms can be straightforward or tricky, depending on the setup. The challenge usually depends on whether you are writing everything from scratch, using a JavaScript library, how the form fields are named, and how well those names match your data model.

A more subtle challenge comes from the limitations of the libraries you choose. Most PDF form automation tools work by directly manipulating AcroForm fields, which means you are often responsible for validation, may need layout workarounds for repeating data, and have limited ability to modify or restructure fields once they are embedded in the PDF.

When populating PDF form fields with structured datasets like the following JSON data:

// service-request.json
[
  {
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "john.doe@example.com",
    "phoneNumber": "+1-555-123-4567",
    "type": "Installation",
    "priority": "High",
    "description": "Need assistance setting up and configuring a new server rack in the data center.\nThis includes mounting all necessary equipment, installing power distribution units, managing cable organization, and ensuring proper ventilation and power balance.\n\nAfter the physical setup is complete, please verify all network connections, confirm switch and port configurations, and ensure that each device in the rack can successfully communicate across the network.\nProvide detailed documentation of configurations, cabling, and connectivity test results once verification is complete."
  }
]

Most libraries simply map data into AcroForm fields and then flatten the PDF into static elements. Unlike most tools, Joyfill Form Builder and Filler SDK provides a more flexible abstraction layer that supports defining and validating fields, updating their structure over time, and conditionally showing or hiding elements, all without being tied to the PDF internal layout.

This guide shows how to use Joyfill to programmatically fill PDF forms in Node.js. We will cover reading fields, inserting data, and saving the PDF to create a reproducible workflow.

Why use Joyfill to Programmatically fill PDF Forms?

Traditional JavaScript PDF libraries focus on direct field manipulation. You parse the PDF, find matching field identifiers, inject values, then flatten everything. This approach works for small and stable forms, but it quickly breaks down as complexity grows.

A major limitation comes from the underlying PDF technologies themselves. PDF forms are built on two incompatible architectures: AcroForms and XFA (XML Forms Architecture). Most libraries only support one of them, usually AcroForms. As a result, XFA fields are often ignored entirely, leaving sections of your form blank when filled programmatically.

Even when fields are supported, developers still run into challenges when:

Field names do not map cleanly to the data model
The form structure needs to evolve
Layout changes frequently
Conditional visibility or computed values are required
Business logic must live outside the PDF binary

Joyfill removes these constraints by representing PDF forms as a JoyDoc. The PDF becomes a visual layer, while the JoyDoc serves as the source of truth for field structure, data, metadata, and layout. Instead of interacting with brittle PDF internals, developers work with a predictable JSON model that remains stable, even when templates change. This is especially valuable when the same dataset needs to populate multiple document formats.

Key advantages for developers

You work with a JSON schema rather than PDF internals

JoyDoc represents your form in a structured JSON format. Each page, field, and resource is addressable through identifiers, making it simple to fetch, update, or compose documents through code rather than manual layout editing.

Every field has a stable identifier

Instead of guessing where values belong, you reference clear identifiers that do not change even if the document layout moves. This lowers maintenance cost and removes the need for repeated parsing.

Metadata lets you enrich documents

You can attach metadata to documents, pages, and fields. This enables structured workflows like tagging fields for export, versioning forms, or passing custom rules along with templates.

Formulas give fields logic

Formulas allow fields to compute values from other fields. For example, summing rows, handling default values, or applying conditional logic. No additional code is required for these computed results once the formulas are defined.

Better adaptability over time

If the PDF form changes, the identifiers and JSON structure allow you to update the document without rewriting your automation logic. You are not locked into the PDF internal layout.

Consistent PDF Forms

Most problems with programmatically filling PDF forms start long before any code runs. They are usually caused by how the form was authored. A poorly structured PDF form can make automation painful, no matter how clean your code is.

Standardize Form Structure Through JoyDoc

With Joyfill, this complexity disappears entirely. Forms created through Joyfill are represented as JoyDocs, a unified format that provides a consistent, predictable structure regardless of the underlying PDF technology. You don't need to worry about incompatible form types, fields that fail to populate, or data that vanishes during processing. Everything is managed through a single, stable model that keeps your form definitions and data perfectly aligned, every time.

For example, to create a PDF form using Joyfill, start by setting up a Joyfill form builder environment.

Create a new folder named joyform and open it in your editor of choice.
Install the project dependencies using your preferred package manager.
```
npm install express ejs lowdb
```

Add a views/builder.ejs file to the project.

This file will serve as the main page for working with your form. It can load an existing template or create a new one when you open it in the browser.

<!-- views/builder.ejs -->
<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Form Builder</title>
  <script src=" https://cdn.jsdelivr.net/npm/@joyfill/components@latest/dist/joyfill.min.js"></script>
</head>

<body>
  <div id="joyfill"></div>
  <script>
    <% if (form) { %>
      const doc = <%- form %>;
    <% } %>

    <% if (!form) { %>
      const doc = Joyfill.getDefaultDocument();
      doc.name = <%- JSON.stringify(name) %>
    <% } %>

          Joyfill.JoyDoc(
            document.getElementById('joyfill'),
            {
              doc,
              mode: 'edit',
              onChange: async (changelogs, updatedDoc) => {
                // Log document changes to the console.
                console.log(changelogs);

                // Persist changes
                try {
                  await fetch('/form', {
                    method: 'POST',
                    body: JSON.stringify(updatedDoc),
                    headers: {
                      'Content-Type': 'application/json',
                    },
                  });

                  console.log(`Successfully updated ${updatedDoc.name}`);
                } catch (e) {
                  console.error(e);
                  alert(`Failed to update ${updatedDoc.name}: ${e.message}`);
                }
              },
            }
          );

  </script>
</body>

</html>

Add an index.js file to the project and save the following script as its contents:

// index.js
const { JSONFilePreset } = require('lowdb/node');
const express = require('express');

(async () => {
  // Create a data store for JoyDoc PDF form storage
  const db = await JSONFilePreset('db.json', {
    form: [],
  });

  // Configure an express application
  const app = express();

  app.set('view engine', 'ejs');

  app.use(express.json());
  app.use(express.urlencoded({ extended: false }));

  // Retrieve a PDF form for editing
  app.get('/form/:name', async (req, res) => {
    const { name } = req.params;
    let form = db.data.form.find((d) => d.name === name);

    res.render('builder', { form: JSON.stringify(form), name });
  });

  // Create or update form
  app.post('/form', async (req, res) => {
    const form = req.body;
    const formIndex = db.data.form.findIndex((d) => d.name === form.name);

    if (formIndex === -1) {
      // Save new PDF form
      db.data.form.push(form);
      await db.write();

      res.end();
      return;
    }

    // Update existing form
    db.data.form[formIndex] = form;
    db.write();

    res.status(200).end();
  });

  const port = 3000;

  app.listen(port, () => {
    console.log(`Form builder is listening on port ${port}`);
  });
})();

Run the script to start the express server.
```
node index
```
Visit http://localhost:3000/form/service-request in your web browser. You should see the following PDF form builder.

Use Consistent, Meaningful Field Names

Automation depends on predictable field names. If your fields are named things like text1, text2, or field3, you will waste time figuring out what maps where during initial development and subsequent maintenance. To avoid this pitfall, always use clear, predictable names that match your data model (e.g., firstName, emailAddress, priority, etc.).

A few minutes spent creating a proper PDF form with consistent naming and accessible fields will save hours of debugging later. The cleaner the source form, the simpler the automation.

For example, add fields that you would normally find on a service request form to the form and give each field a human-friendly name through the identifier field as shown below.

At this point, the content of the project’s db.json file should look like the following:

// db.json
{
  "form": [
    {
      "_id": "69042cc6f71bde2d6304d0f1",
      "identifier": "doc_69042cc6f71bde2d6304d0f1",
      "name": "service-request",
      // form fields,
      "fields": [
        {
          "file": "69042cc6913ba9fae414b0b4",
          "_id": "69042cd8ca31952ab8f9c979",
          "type": "block",
          "title": "Heading Text",
          "value": "Service Request",
          "identifier": "field_69042cd8ca31952ab8f9c979"
        },
        {
          "file": "69042cc6913ba9fae414b0b4",
          "_id": "69042d04784f9cfbe61c5849",
          "type": "text",
          "title": "First Name",
          "identifier": "firstName"
        },
        {
          "file": "69042cc6913ba9fae414b0b4",
          "_id": "69042d4e901859cad7a2e670",
          "type": "text",
          "title": "Phone Number",
          "identifier": "phoneNumber"
        },
        {
          "file": "69042cc6913ba9fae414b0b4",
          "_id": "69042d6c44cc56d50f44fdbc",
          "type": "text",
          "title": "Email Address",
          "identifier": "emailAddress"
        },
        {
          "file": "69042cc6913ba9fae414b0b4",
          "_id": "69042d7d758727e69c32a92d",
          "type": "text",
          "title": "Last Name",
          "identifier": "lastName"
        },
        {
          "file": "69042cc6913ba9fae414b0b4",
          "_id": "69042e0ea372aeb632c9421b",
          "type": "dropdown",
          "title": "Service Type",
          "options": [
            {
              "_id": "69042cc675376b64eddda857",
              "value": "Yes",
              "deleted": true
            },
            {
              "_id": "69042cc6a82115b235236847",
              "value": "No",
              "deleted": true
            },
            {
              "_id": "69042cc6ec92f77bcb4a3f65",
              "value": "N/A",
              "deleted": true
            },
            {
              "_id": "69042e4713ed9ae0610ce289",
              "value": "Installation",
              "width": 100,
              "deleted": false
            },
            {
              "_id": "69042e66949791af17b4b077",
              "value": "Maintenance & Repair",
              "width": 100,
              "deleted": false
            },
            {
              "_id": "69042e73c4be2641732f4cb1",
              "value": "Consultation",
              "width": 100,
              "deleted": false
            },
            {
              "_id": "69042e7eba7a43ca20422a1e",
              "value": "Technical Support",
              "width": 100,
              "deleted": false
            }
          ],
          "identifier": "type",
          "value": ""
        },
        {
          "file": "69042cc6913ba9fae414b0b4",
          "_id": "69042eaefd0e2580a68764a8",
          "type": "multiSelect",
          "title": "Priority",
          "multi": false,
          "options": [
            {
              "_id": "69042cc6dd4dbf98302c7fdd",
              "value": "Low",
              "deleted": false
            },
            {
              "_id": "69042cc6c63dca3d9dfc82f6",
              "value": "Medium",
              "deleted": false
            },
            {
              "_id": "69042cc66bc177e4f7fdb55f",
              "value": "High",
              "deleted": false
            },
            {
              "_id": "69042f57f9713f03bacca8dd",
              "value": "Urgent",
              "width": 0,
              "deleted": false
            }
          ],
          "identifier": "priority"
        },
        {
          "file": "69042cc6913ba9fae414b0b4",
          "_id": "69042f96d4d94ea2103d9754",
          "type": "textarea",
          "title": "Service Description",
          "identifier": "description",
          "value": ""
        }
      ]
    }
  ]
}

Programmatically Fill the PDF Form

Now that we have a properly structured fillable form in the form of a JoyDoc, the next step is to map data to each form field. This data can come from JSON objects, database records, or other sources within your application. The goal remains the same: populate each PDF form field with its corresponding data field.

In the case of our current example project, using the service-requests.json file from the opening section of this post should suffice.

Add a fill-forms.js file to the project and save the following as its contents:

// fill-forms.js
// Retrieve service request PDF form
const form = require('./db.json').form.find(
  (f) => f.name === 'service-request'
);
// Retrieve service requests from data source
const requests = require('./service-requests.json');
const puppeteer = require('puppeteer');
const { join } = require('path');
const { existsSync, mkdirSync, writeFileSync } = require('fs');

async function generatePDFs(requests) {
  // Create output folder for filled out PDFs
  if (!existsSync('pdfs')) {
    mkdirSync('pdfs');
  }

  const browser = await puppeteer.launch();
  const page = await browser.newPage();

  await page.addScriptTag({
    url: 'https://cdn.jsdelivr.net/npm/@joyfill/components@latest/dist/joyfill.min.js',
  });

  // Fill each form in a headless browser and save it to a PDF file.
  for (let req of requests) {
    const populatedForm = fillFormFields(req, form);

    console.log(`Filling out ${req.firstName} ${req.lastName}'s form`);

    await page.evaluate((populatedForm) => {
      const container = document.createElement('div');
      container.id = 'joyfill';
      document.body.appendChild(container);
      document.body.appendChild(container);
      Joyfill.JoyDocExporter(container, {
        doc: populatedForm,
        config: { page: { height: 1056, width: 816, padding: 0 } },
      });
    }, populatedForm);

    await page.pdf({
      path: join('pdfs', `${populatedForm.name}.pdf`),
    });

    await page.evaluate(() => {
      document.querySelector('#joyfill').remove();
    });
  }

  await browser.close();
}

function fillFormFields(request, form) {
  const filledDocument = { ...form };

  // Set the PDF document's name
  filledDocument.name = `${filledDocument.name} - ${request.firstName} ${request.lastName}`;

  // Dynamically populate fields
  for (let field of filledDocument.fields) {
    const id = field.identifier;

    switch (field.type) {
      case 'multiSelect':
        const selected = field.options.find(
          (option) => option.value.trim() === request[id].trim()
        );

        field.value = [selected._id];
        break;
      case 'dropdown':
        const option = field.options.find(
          (option) => option.value.trim() === request[id].trim()
        );

        field.value = option._id;
        break;
      default:
        field.value = request[id];
    }
  }

  return filledDocument;
}

generatePDFs(requests)
  .then(() => {
    console.log('PDFs filled successfully');
  })
  .catch((e) => {
    console.log('Failed to fill PDFs', e);
  });

Add headless browser support to the project by running the following command:
```
npm install puppeteer
```
Run the fill-forms.js script.
```
npm fill-forms
```
This should fill out the form fields, flatten the fields as static elements, and save them to binary PDF files in the pdf subfolder of the project.

Filling Other Form Field Types

The sample project in this post shows how to programmatically populate text fields, dropdowns, and single-choice options. If you need to support additional field types, you would extend the logic in the fill-forms.js script. In practice, this means updating the switch statement to recognize each new field type and apply the appropriate handling behavior.

    switch (field.type) {
      case 'multiSelect':
        const selected = field.options.find(
          (option) => option.value.trim() === request[id].trim()
        );

        field.value = [selected._id];
        break;
      case 'dropdown':
        const option = field.options.find(
          (option) => option.value.trim() === request[id].trim()
        );

        field.value = option._id;
        break;
      case 'date':
        field.value = new Date(request.date).getTime();
        break;
      case 'image':
      case 'file':
        const imageBuffer = fs.readFileSync(request.photoAttachment);
        field.value = imageBuffer.toString('base64');
        break;
      case 'table':
        // Where the value of request.table has the following interface
        // Array<{
        //   _id: string; // row id
        //   deleted: boolean;
        //   cells: {
        //     [cell_id: string]: string; // column id
        //   };
        // }>
        field.value = request.table;
        break;
      case 'chart':
        // Where each point has x (x axis coordinate), y (y coordiante), and a label field.
        field.value[0].points = request.chart.map((point) => ({
          ...point,
          _id: Joyfill.generateObjectId(),
        }));
        break;
      default:
        field.value = request[id];
    }

Conclusion

Filling PDF forms with JavaScript is much simpler when you work with consistent structure instead of raw PDF internals. Joyfill makes this possible by standardizing forms as JoyDoc, keeping fields, metadata, and logic organized in one place.

This gives you reliable identifiers, predictable behavior, and flexibility as forms evolve. If you want a cleaner, more maintainable way to automate PDFs, Joyfill is an easy way to get there.

Need to build PDF capabilities inside your SaaS application? Joyfill helps developers embed native PDF and form experiences directly into their SaaS apps.

Optimizing In-Browser PDF Rendering/Viewing

John Pagley — Thu, 13 Nov 2025 20:08:54 +0000

PDF viewing in the browser seems simple—just embed a file and let the browser do the work, right? But once you need consistent rendering, interactivity, responsive behavior, or support across multiple devices, you realize how little control native PDF viewers actually offer. Developers soon discover a long trail of trade-offs between performance, feature richness, and user experience.

This article walks through the real-world challenges of rendering PDFs directly in the browser, why native support isn’t always enough, what JavaScript-based renderers actually solve (and what they don’t), and how to build responsive, secure, and optimized in-browser PDF viewing experiences—whether you're working with React, plain JavaScript, or commercial SDKs.

Why PDFs in the Browser Still Matter

Even in the age of real-time dashboards and collaborative web apps, PDFs remain one of the most trusted ways to share information. From invoices and contracts to tax reports and form-based submissions, PDFs deliver something the modern web often struggles with: pixel-perfect consistency.

Unlike HTML, which adapts and flows across screen sizes and devices, a PDF guarantees what the recipient sees is exactly what you intended—no broken layouts, missing fonts, or unpredictable CSS rendering. And for many industries (legal, medical, insurance, finance), that level of visual and structural fidelity isn’t just nice to have—it’s a requirement.

This is why viewing PDFs directly in the browser has become a core expectation. For users, it removes the friction of having to download a file and open it in another app. For developers, it keeps the experience inside your product, where you can measure engagement, add interactivity, and maintain tighter control over document behavior.

But here's the twist: while browsers technically support PDFs natively, they don’t always support them well—especially when you need fine-grained control over layout, zoom, page navigation, annotations, or analytics. That's where custom PDF renderers and smart optimizations come in.

The Core Rendering Approaches (and Their Trade-Offs)

Rendering PDFs in the browser typically comes down to two major approaches, each with its own set of advantages and trade-offs. Choosing the right one depends on your product goals, audience, and how much control you need over the viewing experience.

1. Native Browser Rendering (Object/Embed/Iframe)

The simplest way to display a PDF in the browser is to let the browser handle it directly. This can be done using standard HTML elements like <iframe>, <object>, or <embed>.

<iframe src="example.pdf" width="100%" height="600px"></iframe>

Pros:

Zero dependencies — just plain HTML.
Fast and lightweight.
Browsers handle rendering natively (Chrome, Firefox, Safari all support PDFs out-of-the-box).
Supports deep-linking (e.g., document.pdf#page=2).

Cons:

No UI control — you're stuck with the browser’s viewer.
Styling and theming? Not possible.
Inconsistent behavior across browsers (e.g., toolbar visibility, scroll behavior).
No analytics, event tracking, or hooks into the PDF content.
Difficult to preload or stream pages progressively.

In short: great for quick wins, but limited for anything custom or user-focused.

2. JavaScript-Based Viewers (e.g., PDF.js, PDF.js Express, commercial SDKs)

Instead of relying on the browser’s built-in viewer, JavaScript libraries parse and render PDFs manually—usually by painting them onto <canvas> elements or injecting SVGs. This gives you total control over the viewing experience.

Pros:

Full control over layout, UI, and user interactions.
Easier to track usage, add toolbars, implement zoom, page jump, and more.
Can support annotations, form filling, digital signatures, and other interactivity.
Works well with modern frameworks (React, Vue, etc.) via wrappers.

Cons:

Performance-heavy on large documents or mobile devices.
Requires thoughtful optimization (lazy loading, virtualization, offscreen rendering).
Larger bundle sizes and longer initial load times.
May miss advanced browser features like PDF prefetching or native memory optimizations.

This is the dominant strategy for most modern web apps that treat PDFs as more than just static downloads.

Takeaway:

If you just need to show a static PDF quickly, use the browser’s native renderer. But if your product relies on PDFs as a core part of the user experience—think dashboards, annotations, or dynamic forms—JavaScript-based viewers are the way forward.

The State of PDF.js and Other Viewer Libraries

When it comes to in-browser PDF rendering, PDF.js remains the most widely used open-source option—but it's not the only one in the ecosystem. Each tool brings its own trade-offs in performance, features, and developer experience.

PDF.js (by Mozilla)

PDF.js is a JavaScript library developed by Mozilla that parses and renders PDFs using HTML5 and canvas.

Strengths:

Free and open-source.
Actively maintained and widely supported.
Works directly in all modern browsers without plugins.
Supports deep linking, basic text selection, and page navigation.

Limitations:

Not React-native — requires wrappers like react-pdf.
Minimal built-in UI (you’ll need to build toolbars or controls yourself).
Performance degrades on large or complex documents.
Limited out-of-the-box support for annotations, form filling, or signatures.
Rendering can appear blurry or imprecise, especially on high-DPI screens.

react-pdf

A thin wrapper around PDF.js, react-pdf makes it easier to integrate with React projects.

Pros:

Clean and declarative React API.
Better suited for SPAs and componentized UIs.
Easy to combine with react-virtualized or lazy loading for performance.

Cons:

Inherits the same limitations from PDF.js under the hood.
Requires extra libraries or manual work for advanced features.

A Quick Comparison

Library	UI Included	Annotations	Form Filling	Framework-Friendly	Open Source
PDF.js	❌	View-only	Limited	✅ (manual)	✅
react-pdf	❌	View-only	Limited	✅ (React)	✅

Takeaway:

For most frontend projects, PDF.js or react-pdf are good starting points—but if your product demands a polished viewer, form functionality, or document intelligence (like redaction or signing), you’ll quickly outgrow them. Be realistic about your requirements upfront to avoid costly rewrites later.

Rendering Performance Bottlenecks (And How to Solve Them)

Rendering PDFs in the browser sounds easy—until you try it on a large file, a slow mobile device, or in a tab that’s already chewing up memory. Performance bottlenecks are one of the most reported pain points when it comes to delivering a smooth PDF viewing experience in modern web apps.

Here are the most common performance pitfalls—and how to address them effectively.

Bottleneck: Large Files and Slow Initial Loads

The issue:

High-resolution images, embedded fonts, and scanned pages balloon file size, resulting in long download and rendering times—especially on mobile networks.

Solutions:

Compress PDFs before serving: Use PDF optimizers to strip metadata, compress images, and subset fonts.
Linearize PDFs: Also called "web-optimized" PDFs, linearized documents allow browsers to begin rendering the first page before downloading the rest.
Serve from a CDN: Distribute PDFs from edge locations to minimize download latency.

Bottleneck: High CPU and Memory Usage

The issue:

Rendering multiple pages simultaneously or scaling canvases for retina displays can cause browser tabs to freeze or crash.

Solutions:

Virtualization: Only render the visible pages using libraries like react-virtualized or Intersection Observer APIs.
Use HTTP Range Requests: PDF.js can stream portions of a file if the server supports byte-range requests.
Offscreen Canvas Rendering: Render complex elements offscreen and copy them to the visible canvas when needed.
Canvas scaling best practices: Set canvas dimensions in code, not just CSS, to avoid pixelation or blurry text on high-DPI screens.

Bottleneck: Re-rendering and UI Jank

The issue:

Zooming, scrolling, and switching pages often re-triggers expensive layout or canvas redraws.

Solutions:

Throttle or debounce redraw operations.
Layer canvases intelligently: Separate static elements from dynamic ones, so you’re not redrawing the whole page on every interaction.
GPU-friendly transforms: Prefer CSS transform: scale() over canvas context scaling for zooming.

Bottleneck: Mobile Rendering Constraints

The issue:

Mobile browsers have less memory, weaker CPUs, and smaller screens—which compounds every rendering inefficiency.

Solutions:

Lazy load only the first visible page, then load subsequent pages on scroll.
Prioritize low-resolution previews first, with full rendering deferred or manually triggered.
Test with device throttling in browser dev tools to simulate real-world mobile constraints.

Takeaway:

Optimizing PDF rendering isn’t just about making it “work”—it’s about making it fast, smooth, and invisible to the user. Even with lightweight tools like PDF.js, thoughtful optimizations can make the difference between a delightful document experience and a tab crash.

UX and Viewer Design Best Practices

A fast renderer is only half the battle. A great PDF viewing experience also depends on how the viewer feels—how users navigate it, interact with it, and trust it.

Whether you're wrapping PDF.js in a React component or integrating a full-blown viewer SDK, these UX best practices can help your embedded PDF experience feel native, intuitive, and polished.

Navigation Must Feel Natural

Support keyboard shortcuts: Page Up/Down, arrow keys, and Ctrl/Cmd + F (for search) should work as expected.
Smooth scrolling: Avoid janky, page-by-page transitions unless users explicitly choose “single-page” view.
Mini-map or page thumbnails: For longer documents, thumbnails improve orientation and scanning.

Intuitive Zoom and Scaling

Pinch-to-zoom (on mobile): Must be smooth and snappy, not a clunky magnification.
Zoom buttons: Make them accessible and reversible.
Preserve layout: Zooming should never break layout or obscure UI components.

Annotation and Form UX

Show only relevant tools: Don’t overwhelm users with every annotation option—especially if your app only requires signatures or highlights.
Save state persistently: If users add a form field or comment, ensure it auto-saves or warns before they navigate away.
Visual feedback: Hover and focus states matter. PDF elements should feel like part of the app, not an isolated sandbox.

Responsive and Mobile-Friendly

Reflow where possible: For smaller screens, text reflow (even partial) can make documents readable without endless pinch-zooming.
Touch targets: Buttons for download, zoom, and page navigation must meet mobile accessibility standards.
Avoid scroll traps: Ensure nested scroll areas (e.g., inside an iframe) don’t interfere with native page scroll.

Seamless Theming and Branding

Custom viewer chrome (UI elements like toolbars and buttons): If your app uses dark mode or branded buttons, match the PDF viewer to your theme.
Hide unused UI: Toolbars, pagination controls, and download buttons should adapt to your app’s context—not just mimic the generic, desktop-heavy UI patterns found in tools like Adobe Reader.
Minimalist is better: Keep UI elements simple, decluttered, and discoverable.

Takeaway:

The best in-browser PDF viewers are invisible. They feel like a natural extension of the app—not a bolted-on widget. Focus on interaction polish, mobile comfort, and visual harmony, and you’ll elevate PDFs from tolerable to delightful.

Common Security Pitfalls in Embedded Viewers

PDFs aren’t just documents—they can be containers for scripts, metadata, and hidden content. When rendering them inside the browser, especially with JavaScript-based viewers like PDF.js, you inherit a unique set of security concerns that traditional document viewers often guard against by default.

Understanding these risks helps you build safer in-browser PDF experiences—without sacrificing performance or interactivity.

JavaScript Execution Inside PDFs

Many developers don’t realize that PDFs can embed JavaScript—and that some browsers or viewer libraries might execute it depending on their configuration.

Why it's risky: Malicious scripts inside PDFs could trigger cross-site scripting (XSS) attacks, interact with the DOM, or trick users with fake UI overlays.
What to do: Always disable JavaScript execution in your PDF viewer unless explicitly needed. PDF.js has a setting for this: isEvalSupported: false.

Cross-Origin Requests & CORS

If you’re loading PDFs from an external domain (e.g., a CDN or cloud storage), browser security rules kick in.

Why it's risky: Missing or misconfigured CORS headers can block PDF loading or leak sensitive metadata.
What to do: Make sure your server serving PDFs sends the right CORS headers (like Access-Control-Allow-Origin). Also configure PDF viewers to handle blob URLs or pre-signed URLs securely.

Metadata Leaks

PDFs often carry embedded metadata—author name, modification dates, comments, hidden layers—that can unintentionally expose user or business information.

Why it's risky: This metadata can be scraped or displayed via developer tools.
What to do: Sanitize PDFs before serving them. Use a server-side tool (like pdfcpu, qpdf, or Acrobat) to strip out metadata and embedded scripts.

Sandbox Misconfigurations

Using <iframe> to embed native browser viewers is fast—but you must sandbox it correctly.

Why it's risky: Without a sandbox, an iframe can interact with the parent DOM, inject scripts, or leak user data via cookies or storage.
What to do: Add a sandbox attribute to the <iframe> tag. A common secure configuration is:
```
<iframe
src="/path/to/file.pdf"
sandbox="allow-scripts allow-same-origin"
width="100%" height="600px">
</iframe>
```
Adjust the permissions based on your feature needs. And remember: less is safer.

Note: For tighter security, remove allow-scripts unless JavaScript-based PDF features are explicitly needed.

CSP (Content Security Policy) Gaps

Even if your app has a good CSP, it might not protect embedded PDF content—especially if opened in a new tab.

Why it's risky: PDF JavaScript (if not blocked) can sidestep CSP if the file is opened in a separate context.
What to do: Use Content-Disposition: inline with care, and verify how your CSP applies to PDF routes. When in doubt, disable risky features at the server level.

Security isn’t a checkbox—it’s a layering process. Whether you use a native embed or a custom viewer, always treat external PDFs as untrusted input. The more control you have over rendering and behavior, the more secure your in-browser PDF experience becomes.

In the next section, we’ll zoom out and talk about the bigger picture: when to stop building and start buying.

When to Go Beyond Open Source (and Why It’s Okay)

Open-source tools like PDF.js and react-pdf are excellent starting points for rendering PDFs in the browser. They're free, battle-tested, and supported by vibrant communities. But at some point, many teams hit a wall—where features, performance, or maintainability can’t keep up with growing expectations.

Where Open Source Starts to Struggle

Advanced annotations: Need stamp support, ink drawings, or collaborative markup tools? Many open-source viewers only support basic highlight and text notes.
Form logic and validation: Dynamic form behaviors like conditional fields, inline calculations, or real-time validation aren’t typically available.
Redaction, flattening, or digital signatures: These advanced actions are rarely supported in open-source stacks without heavy customization—or not at all.
Consistent cross-browser rendering: PDF rendering may vary slightly across engines, especially with complex layouts or obscure fonts.

Signs You’re Ready for a Commercial SDK

You’re building multi-tenant document-heavy SaaS and want fewer moving parts in your stack.
Your users expect form-aware documents with interactive fields, validations, and save/submit flows.
Your app needs auditability, digital trust, or compliance-ready output—not just a “PDF viewer”.
You want to spend less time maintaining PDF infrastructure and more time shipping your actual product.

Many teams eventually look to managed PDF SDKs or platforms to reduce friction and offload complexity—especially when forms, annotations, or multi-tenant document workflows become central to the product. Joyfill is one such option designed for SaaS apps that need structured, scalable PDF handling without rebuilding everything from scratch.

Final Thoughts: Avoiding Pitfalls While Building for the Long Term

Rendering PDFs in the browser isn’t just a technical checkbox—it’s a user experience challenge, a performance concern, and often a product-defining decision. The surface area seems small (just show a document!), but the deeper you go, the more complex the trade-offs become.

Some teams reach for <iframe> or <embed> and move on. Others embed PDF.js, only to discover performance bottlenecks on mobile, rendering quirks across browsers, or limited feature sets when forms and annotations become a requirement.

There’s no silver bullet. But there are proven practices:

Start small. Use native embedding or open-source libraries to validate your PDF workflows early.
Watch for complexity creep. Forms, validations, annotations, and cross-device behavior compound over time.
Prioritize performance. Stream large files, defer rendering when possible, and optimize for mobile.
Bake in security. Sanitize documents, sandbox your viewer, and control external dependencies.
Know when to build and when to buy. Your engineering time is limited—use it where it matters most.

No matter your stack—vanilla JS, React, Vue, or something else—one thing is clear: in-browser PDF rendering has matured, but getting it right still requires intention. Make those trade-offs visible. Test with real files. And treat your viewer like any other part of your frontend—it’s your product, not an afterthought.

Need to build PDF capabilities inside your SaaS application? Joyfill helps developers embed native PDF and form experiences directly into their SaaS apps.

The Inspiring Story of the Popular Open-Source Library—Shadcn Form Builder

John Pagley — Wed, 29 Oct 2025 18:18:57 +0000

In this video, the host John from Joyfill sits down with Hasan, creator of Shadcn Form Builder, to walk through the project’s journey—from the first idea to its open‑source traction and beyond.

Watch the full video

Where it all began

Hasan explains that the project started as a personal project: he noticed a lack of quality with the current open-source form builders on the web. He began building one himself. He framed it simply: a weekend experiment to see if he could scratch his own itch and build a better tool.

He describes how this led to an initial prototype, and then a decision to open source it publicly. The turning point came when developers started to find it useful and giving him positive feedback.

The unexpected momentum

After publishing the project and sharing it online, Hasan was surprised by how quickly people responded. Within days, the repo gained stars and the conversation spread. He reflects that the project had resonated because it was solving a real problem he had—but one shared by many others.

John asks what surprised him most — Hasan says it was the consensus that yes, there is a need for a tool like this in the community. He emphasizes that he didn’t expect viral growth; he just built something he thought was useful and the community did the rest.

Keeping the project manageable

Hasan is candid about the fact that he has a full‑time job and this is a side effort. He explains how he handles the balancing act:

Keeping the scope tight rather than trying to build everything all at once.
Prioritizing sustainability: not burning out.
Responding to feedback and contributions rather than owning every detail himself.

John presses on how open‑source maintainers often feel the pressure of being the “owner” of the project, and Hasan acknowledges that. His mantra: “Keep it useful, keep it fun.”

Key takeaways for devs and founders

Throughout the conversation, a few recurring lessons emerge:

Build what you yourself need. Your personal pain can point to something that many others share.
Ship early rather than waiting for “perfect”. By putting something out there you start the feedback loop.
Open source fosters community momentum: once other developers find value, they become contributors, advocates.
Balance ambition with sustainability: keeping things small and focused helps maintain momentum without burnout.

Looking ahead

When asked “what’s next”, Hasan doesn’t commit to a large roadmap. Instead, he shares his mindset: evolve the project as the community uses it, listen to what people ask for, and ensure the tool continues to align with what developers actually want. He sees open‑source as a living ecosystem, not a finished product.

Final reflections

By the end of the interview, the story of Shadcn Form Builder reads less like a typical startup narrative and more like what happens when a developer takes matters into his own hands: notices a friction, builds a simple solution for himself, shares it openly—and discovers that the problem exists for many. For technical people and entrepreneurially minded developers, the take‑away is clear: you don’t need a massive plan to build something meaningful. You need curiosity, willingness to ship, and openness to community.

Need to build form capabilities inside your SaaS application? Joyfill makes it easy for developers to natively build, embed, and customize form experiences inside their web and mobile apps.

Refining PDFs after 104 deep developer conversations

John Pagley — Fri, 10 Oct 2025 19:15:28 +0000

Over the past 14 months, we’ve had 100+ in-depth conversations with developers and product teams building SaaS products that needed one common thing: PDF form capabilities. These were not casual chats—they were real discussions with engineers deep in the weeds of PDF workflows, integrations, and the endless quirks of legacy PDF tech. For most, the goal at hand was to build (or buy) a PDF solution to build, fill, and view PDF files inside their applications. The kicker here, was they didn’t want something that looked or felt foreign to their product. Being Joyfill is natively embeddable and customizable, it was one of the desirables that initiated these conversations.

As one of the founders of Joyfill, these conversations became a treasure trove of insights. Ones that we found might be very helpful to many developers. They shaped how we think about PDFs, why developers are frustrated, and where the industry needs to go. Most importantly, they shaped how we’re building Joyfill v2.

So, here are the most common takeaways and lessons we learned from those conversations. I hope they help accelerate your builds.

Lesson 1: JSON-first workflows make pre-filling and extracting data effortless

In nearly every conversation, developers were frustrated by how difficult it was to populate and extract data from PDFs. “We just want to treat the form like a JSON object,” one dev told me. Another said, “I shouldn’t have to reverse-engineer a PDF to insert a first name.” The desire was clear: a schema-driven way to interact with fields like any other part of a web app.

The best approach we’ve seen is a JSON-first form model—where every field has a stable ID, and form state lives in a clean, structured object. It makes pre-filling fields and capturing updates feel like working with any modern UI state. If you’re building or choosing a PDF tool today, lean into this structure—it saves you from brittle workarounds and opens the door to automation, analytics, and scalable form workflows. With Joyfill, this is easy because everything centers around our “JoyDoc”. Which is JSON.

Lesson 2: Data sovereignty must be a first-class feature

Data ownership came up in almost every conversation. Many teams work in industries—finance, field service, healthcare, government—where storing user data in third-party clouds isn’t always an option or preference.

Modern PDF SDKs should offer both managed and self-hosted data options. The ability to intercept form payloads and store them in your own system isn’t just a nice-to-have—it’s a requirement for teams with compliance needs or strict data policies.

By default, Joyfill stores data in our cloud for convenience. But for teams needing full control, we built a self-hosted data mode. In this mode, you handle the JSON payloads entirely within your own infrastructure, giving you the compliance and control you need.

Lesson 3: Self-hosting is about control and peace of mind

Some developers asked, “Can I just spin this up in Docker and be done?” The answer is: not exactly—but you can achieve the same outcome.

While we don’t provide a single Docker image, our self-hosted data mode gives you the ability to keep all data handling on your side. As mentioned above. For rendering PDFs in your own environment, you can pair the Joyfill Export SDK with a headless browser like Puppeteer or browserless. This approach keeps rendering and export pipelines under your control without tying you to any specific cloud service.

Lesson 4: Customization isn’t a nice-to-have—it’s table stakes

No two SaaS apps look the same, and developers want their PDFs and UI to match their brand seamlessly. That includes theming, branding, and disabling or enabling UI elements at a granular level. Developers should be able to control what users see and how it looks—down to the font, button visibility, and interaction settings.

Joyfill supports theming through two powerful props in React:

fieldOptions: Define draggable field types with custom styles, default values, and icons.
fieldSettings: Fine-tune UI elements—disable certain style options (like font size), hide titles, control upload/delete buttons, and more.

This flexibility ensures the PDF solution feels like part of your product, not an external 3rd-party widget.

Lesson 5: Smart PDF forms require built-in validation and logic

Form validation was non-negotiable for nearly every team. Developers wanted not only required fields but also conditional logic to make PDF forms dynamic and user-friendly. Many struggled with brittle validation logic—especially in multi-step flows or mobile forms.

PDF tools need to support native validation and conditional logic, ideally built into the schema or SDK. Whether it’s required fields, field visibility based on answers, or section-level rules, this logic is crucial for real-world use.

Lesson 6: Localization needs to be possible—even if not automatic

Global products need localization, and several teams asked about multilingual support. While Joyfill doesn’t yet offer built-in localization or automatic language switching, you can still localize manually by constructing JoyDoc templates and field labels in any language. This gives you the flexibility to meet international requirements today while we work toward native i18n solutions in the future.

Lesson 7: Fine-grained UI control makes the difference

Finally, developers wanted to control exactly what their users could see and do in the PDF experience. They wanted to control the entire user interaction model. Some needed strict read-only modes for audit scenarios. Others wanted to disable editing features like uploads or deletions. In these cases, “default behavior” wasn’t good enough.

To meet these needs, tools should offer fine-grained control over form interactivity. This includes configurable modes—like edit, fill, or read-only—as well as toggles for individual UI elements at the field, page, or document level. Developers want to tailor the form experience to specific roles, stages, or workflows—without having to fork the library or hack around the defaults.

The Joyfill PDF SDK gives you this flexibility with two mechanisms:

The mode prop: Switch between edit, fill, and readonly modes.
fieldSettings: Enable or disable specific UI elements at the file, page, or field level—like hiding upload buttons, style controls, or delete actions.

This level of control ensures the user experience matches your exact use case.

The Big Takeaway: The pair of simplicity, extensibility, and control wins

Talking to over 100 developers taught us that building with PDFs isn’t just about generating documents—it’s about owning the data, controlling the experience, and removing legacy complexity.

Aside from the technical takeaways, many of the questions we receive are general can-you-do PDF questions, but a significant number center around the specific use cases products are trying to solve. For example, how to implement a PDF form filler, an e-signature solution, or a full multi-step data input workflow.

Beyond feature-specific questions, the focus is often on how to actually implement the product experience. The conversations become very scenario-driven. In many cases, we find ourselves guiding users through the thought process of solving their problem with Joyfill (or other libraries for that matter) — not just explaining features, but helping them envision the full solution.

At Joyfill, these conversations directly influenced how we’re approaching v2: a simpler, more extensible SDK that puts developers in control of all the pieces. If you’re building a SaaS product and fighting with PDFs, know this: it doesn’t have to be painful. Let’s talk — we are happy to lend a hand.

We’re solving PDFs for developers—one conversation at a time. On to the next 100…

Introducing Formulas: Create smarter forms with calculations, automation, and much more

John Pagley — Fri, 10 Oct 2025 00:27:38 +0000

We’re excited to announce a powerful new feature in our form builder SDK: Formulas.

With formulas, your forms aren’t just static fields anymore—they become dynamic, programmable, and intelligent. Whether you’re building internal tools, customer-facing apps, or large-scale data collection systems, formulas bring new levels of flexibility and automation.

What developers gain

Programmatic power: Define relationships between fields, perform calculations, and apply logic directly within your forms.
Advanced data handling: From handling numbers, strings, dates, arrays, and objects to nesting functions and resolving dependencies, formulas give you precise control over data flow.
Consistency at scale: Apply logic once and trust it everywhere—ensuring clean, predictable data without reinventing the wheel.

What end users gain

Smarter experiences: Forms that adapt on the fly—automatically calculating totals, validating inputs, and populating values.
Reduced friction: Less manual data entry and fewer errors thanks to built-in automation.
Clarity and confidence: End users see immediate results from their inputs, making forms more interactive and intuitive.

Watch the post release discussion:

https://youtu.be/7i20iXtMamI?si=CXQkeemcVWIdjtoy

Build beyond the basics

With support for functions, operators, and flexible value references, formulas unlock a new dimension of what your forms can do. From simple field calculations to complex logic across tables and collections, the possibilities are wide open.

This is just the beginning—we’re building the foundation for the next generation of form intelligence.

Learn more by viewing our formulas developer documentation.

*This is a beta release. Your early feedback is greatly appreciated.

Making sure your PDF compliance and privacy requirements are met with JoyDoc

John Pagley — Wed, 17 Sep 2025 21:25:06 +0000

TL;DR:
Picking a random PDF tool can quietly break your compliance. Cloud-hosted PDF builders often route data through outside servers, change terms without warning, skimp on encryption, and lack the audit logs regulators expect—putting you at risk with GDPR, HIPAA, CCPA, and more. The safer path is to keep control: self-host Joyfill’s Form Builder, model documents as JSON with JoyDoc, collect inputs via your own HTML forms, then generate PDFs on your own infrastructure (e.g., with the JoyDoc Exporter + Puppeteer). This setup lets Legal get clear custody and audit trails, Engineering keep a simple, flexible workflow, and Product avoid surprise data exposure—all while meeting strict privacy promises to users. In short: own your data flow, prove who accessed what and when, and ship PDFs without handing sensitive info to third parties.

Many companies underestimate how something as simple as choosing a PDF form builder or a library can affect compliance. When multiple teams are involved, priorities diverge: Management focuses on cost, speed, and scalability; Legal focuses on regulatory obligations and liability; Design and Engineering prioritize user experience, functionality, and integration.

Yet, it's easy to overlook how a seemingly minor detail such as where and how a third-party PDF filler or a PDF builder stores and processes user data can undermine all other priorities by introducing serious compliance violations.

Common Risks in Everyday PDF Workflows

Because many PDF tool vendors operate as cloud-managed services, confidential data may pass through external servers or even jurisdictions where data and processing regulations may conflict with GDPR, NEN, HIPPA, CCPA, and dozens of other regional regulations your company has promised to uphold.

A trend that's got most companies that care about data privacy on their toes is how a PDF form creator vendor for example, updates its terms of service and privacy policy without adequately notifying its customers. So, what seemed like a compliant solution yesterday might expose your organization to significant regulatory penalties tomorrow.

Some PDF processors use outdated encryption methods or fail to maintain end-to-end encryption throughout the document lifecycle, creating vulnerabilities that could result in compliance violations if sensitive data is compromised.

Compliance frameworks often require comprehensive audit trails showing who accessed what documents when and from where. Many PDF tools lack the detailed logging capabilities necessary to satisfy these requirements.

To properly manage such risks, an organization must proactively identify and mitigate both common and less obvious compliance risks as soon as they decide to collect, process, or share confidential data. The moment user data enters your system, you are responsible for its security, access control, and for maintaining the privacy guarantees you’ve made to both your users and regulatory bodies of jurisdictions where they live.

How JoyDoc and Joyfill’s Self-Hosted Approach Facilitate Compliance

Organizations with strict compliance requirements can’t afford to risk unauthorized access to PDF documents or user data collected through PDF forms hosted by third-party PDF services with opaque handling policies. That’s why many teams are turning to self-hosted PDF solutions built on tools like Joyfill's web and mobile components.

Although Joyfill offers a managed service, its tools are also designed to accommodate compliance requirements through integration paths where you retain full control of your data.

Such an integration strategy is made possible by JoyDoc, a JSON schema for transferring data between Joyfill platform solutions such as the mobile/web UI components, and the PDF form builder and PDF filler SDK.

Because JoyDoc represents a PDF document as JSON, organizations could avoid compliance issues using the following PDF generation workflow:

Self-hosting Joyfill’s PDF Form Builder SDK.
Creating an empty but reusable JoyDoc PDF document using the self-hosted form builder.
Collecting user input through HTML forms.
Generating actual PDF documents by populating reusable JoyDocs from such user input. This can be done in your own infrastructure using Joyfill’s PDF Exporter SDK and a headless browser like Puppeteer.

Step 1: Self-host Joyfill’s Form Builder SDK

Joyfill’s Form Builder SDK offers a simple drag-and-drop interface for authoring a PDF document’s fields in JoyDoc format. Self-hosting the SDK allows you to:

Control where your data is stored and how it’s processed.
Reuse the created document across your applications by updating its fields from user data collected through HTML forms.

For example, a simple patient portal that allows admins to create reusable PDF templates with JoyDoc, patients to schedule appointments through HTML forms, and the system to generate PDFs from each appointment’s details might look as follows:

Create a new folder named patient-portal and open it in your preferred code editor.
Run the following command in the code editor’s integrated terminal to configure a new NodeJS project:
```
npm init -y
```
Install the project’s dependencies by running the following commands:
```
npm install express lowdb puppeteer
```

express exposes the web application to your computer’s network.
lowdb stores data in a single JSON file.
puppeteer will use JoyDoc’s exporter to generate PDFs in a headless browser.

Change the value of the type field in the project’s package.json file to make it compatible with lowdb which is going to be used as a database.

Create an index.js file in the project and copy the following code to it:

// index.js
import { JSONFilePreset } from 'lowdb/node';
import express from 'express';

(async () => {
  // Create a data store for JoyDoc and appointments storage
  const db = await JSONFilePreset('db.json', {
    joydoc: [],
    appointment: [],
  });

  // Configure an express application
  const app = express();
  app.use(express.static('static'));
  app.use(express.json());
  app.use(express.urlencoded({ extended: false }));

  // Retrieve all JoyDoc
  app.get('/joydoc', async (req, res) => {
    const documents = db.data.joydoc.map((doc) => doc.name);
    res.status(200).json(documents);
  });

  // Create a reusable JoyDoc
  app.post('/joydoc', async (req, res) => {
    const doc = req.body;
    let savedDoc = db.data.joydoc.find((d) => d.name === doc.name);

    if (savedDoc) {
      res
        .status(400)
        .json({ error: 'A document with the same name already exists' });

      return;
    }

    // Save new document
    db.data.joydoc.push(doc);
    await db.write();

    savedDoc = db.data.joydoc.find((d) => d.name === doc.name);
    res.status(201).json(savedDoc);
  });

  // Retrieve a JoyDoc for editing
  app.get('/joydoc/:name', async (req, res) => {
    const { name } = req.params;
    let savedDoc = db.data.joydoc.find((d) => d.name === name);

    if (!savedDoc) {
      res.status(404).json({ error: 'Not found' });

      return;
    }

    res.status(200).json(savedDoc);
  });

  // Update an existing JoyDoc as it's edited
  app.put('/joydoc', async (req, res) => {
    const update = req.body;
    const docIndex = db.data.joydoc.findIndex((d) => d.name === update.name);

    if (docIndex === -1) {
      res.status(404).json({ error: 'Not found' });
      return;
    }

    db.data.joydoc[docIndex] = update;
    db.write();

    res.status(200).end();
  });

  // Schedule a new appointment
  app.post('/appointment', async (req, res) => {
    db.data.appointment.push(req.body);
    await db.write();

    const [date, time] = req.body.time.split('T');
    res.status(201).send(
      `<body style="min-height: 90vh; display: flex; justify-content: center; align-items: center;">
          <p style="font-size: 2rem;">You successfully scheduled an appointment for ${time} on ${date}.</p>
        </body>
        `
    );
  });

  const port = 3000;

  app.listen(port, () => {
    console.log(`Patient portal is listening on port ${port}`);
  });
})();

Create a static folder in the project.

Add an index.html file to the just created static folder and copy the following HTML to it:

<!-- static/index.html -->
<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Patient Portal</title>
  <style>
    body {
      margin: 0;
      padding: 0;
      min-height: 100vh;
      display: flex;
      justify-content: center;
      align-items: center;
      gap: 7.5vmin;
    }

    a {
      font-size: 2rem;
      border: 1px solid #ddd;
      padding: 1em;
      border-radius: .5em;
    }
  </style>
</head>

<body>
  <a href="/document.html" class="cta">Manage Documents</a>
  <a href="/appointment.html" class="cta">Schedule Appointment</a>
</body>

</html>

Start the web server by running the following command:
```
node index.js
```
Visit http://localhost:3000 in your browser. You should see the following web page:

The app currently offers the options of managing existing JoyDocs or scheduling an appointment. Let's make a page to create and edit JoyDocs below.

Add a document.html file to the static folder and save the following markup to it:

<!-- static/document.html -->
<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Manage Documents</title>
  <style>
    .action-form {
      display: flex;
      justify-content: center;
      align-items: center;
      min-height: 100vh;
      gap: 2em;
    }

    .field-group {
      border: 1px solid #ddd;
      padding: 1em;
      flex-basis: 400px;
      max-width: 400px;
      height: 240px;
    }

    .field-group>.field-label {
      font-size: 1.75em;
    }

    .hint {
      font-size: 0.75em;
      margin-top: 2px;
    }

    #old-document,
    #new-document,
    #create-new {
      font-size: 1.25rem;
    }

    #old-document,
    #new-document,
    #create-new,
    .field-group>.field-label {
      font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
        Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
    }

    #old-document {
      flex: 1;
      cursor: pointer;
      width: 100%;
      padding: 0.8em;
      border-radius: 0.25em;
    }

    #old-document,
    ::picker(select) {
      appearance: base-select;
    }

    #new-document {
      padding: 0.8em;
      display: block;
      max-width: 100%;
      border-radius: 0.25em;
    }

    #create-new {
      display: block;
      border: none;
      border-radius: 0.25em;
      background-color: green;
      color: white;
      padding: 0.8em 1em;
      font-size: 1em;
    }
  </style>
</head>

<body>
  <form action="" class="action-form">
    <div class="field-group">
      <p class="field-label">Edit existing document</p>
      <select id="old-document">
        <option value="" selected class="document-option">Select a document</option>
      </select>
    </div>

    <div class="field-group">
      <p class="field-label">Create new document</p>
      <input type="text" id="new-document" placeholder="Document name">
      <p class="hint">E.g. <i>Patient Appointment</i></p>
      <button id="create-new">Create</button>
    </div>
  </form>

  <div id="joyfill"></div>

  <script type="application/javascript"
    src="https://cdn.jsdelivr.net/npm/@joyfill/components@latest/dist/joyfill.min.js"></script>

  <script src="/document.js"></script>

  <script>
    (async () => {
      let docNames = [];

      // Retrieve existing documents
      try {
        const res = await fetch('/joydoc', {
          headers: { 'Content-Type': 'application/json' },
        });

        docNames = await res.json();
      } catch (e) {
        console.error(e);

        alert(
          `Failed to retrieve list of existing documents: ${JSON.stringify(e.message)}`
        );
      }

      // Add the names of existing documents to the select field to the UI
      let docList = document.querySelector('#old-document');

      for (let name of docNames) {
        let option = document.createElement('option');

        option.textContent = name;
        option.value = name;

        docList.appendChild(option);
      }

      //  Handle new document creation
      document
        .querySelector('#create-new')
        .addEventListener('click', createNewDocument);

      // Handle document selection
      document
        .querySelector('#old-document')
        .addEventListener('change', loadExisting);
    })();

    // Create a new document
    async function createNewDocument(e) {
      e.preventDefault();

      let name = document.querySelector('#new-document').value;
      let blankDocument = Joyfill.getDefaultDocument();

      blankDocument.name = name;

      // Save the document to the store
      const res = await fetch('/joydoc', {
        method: 'POST',
        body: JSON.stringify(blankDocument),
        headers: {
          'Content-Type': 'application/json',
        },
      });

      const doc = await res.json();

      if (doc.error) {
        const msg = `Failed to save ${blankDocument.name}: ${doc.error}`;

        console.error(msg);
        alert(msg);

        return;
      }

      initFormBuilder(doc);
      console.log(`Saved ${doc.name}`);
    }

    function initFormBuilder(doc) {
      // Partially reset layout
      document.querySelector('.action-form').style.display = 'none';

      Joyfill.JoyDoc(document.getElementById('joyfill'), {
        doc,
        mode: 'edit',
        onChange: async (changelogs, updatedDoc) => {
          // Log document changes to the console.
          console.log(changelogs);

          // Update document
          try {
            await fetch('/joydoc', {
              method: 'PUT',
              body: JSON.stringify(updatedDoc),
              headers: {
                'Content-Type': 'application/json',
              },
            });

            console.log(`Successfully updated ${updatedDoc.name}`);
          } catch (e) {
            console.error(e);
            alert(`Failed to update ${updatedDoc.name}: ${e.message}`);
          }
        },
      });
    }

    async function loadExisting(e) {
      e.preventDefault();

      const name = document.querySelector('#old-document').value;

      try {
        const res = await fetch(`/joydoc/${name}`, {
          headers: { 'Content-Type': 'application/json' },
        });

        const doc = await res.json();

        initFormBuilder(doc);
      } catch (e) {
        console.error(e);

        alert(
          `Failed retrieve list of existing documents: ${JSON.stringify(e.message)}`
        );
      }
    }
  </script>
</body>

</html>

Step 2: Create a Resusable JoyDoc

Click the Manage Documents link on http://localhost:3000. It should display the options shown in the image below. Create a new document named Patient Appointment as shown below.

Add fields to the document as demonstrated in the following image. For each field, set an appropriate title, identifier, etc.

Step 3: Collect User Input from HTML Forms

Back in your code editor, add an appointment.html file to the static folder and copy the following markup into it:

<!-- static/appointment.html -->
<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Patient Appointment</title>
  <style>
    .appointment-wrapper {
      background-color: #ecedf3;
      min-height: 100vh;
      background-color: #ecedf3;
      font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
        Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
      color: #2c3345;
    }

    .appointment {
      background-color: #fff;
      margin: 0 auto;
      padding: 5vmin;
      max-width: 816px;
      min-height: 100%;
      display: flex;
      justify-content: center;
      align-items: center;
      flex-wrap: wrap;
      row-gap: 24px;
    }

    .title,
    .name {
      flex: 0 0 100%;
      max-width: 100%;
    }

    .name {
      display: flex;
      justify-content: space-between;
    }

    .name>.field-control {
      flex: 0 0 40%;
      max-width: 40%;
    }

    .field-label,
    input.field {
      display: block;
    }

    .field-label {
      margin-bottom: 4px;
    }

    input.field {
      padding: 0.8em;
      width: 100%;
    }

    .appointment>.field-group {
      flex: 0 0 100%;
      max-width: 100%;
    }

    .field-hint {
      margin-top: 4px;
      font-size: 14px;
    }

    .contact-preference>label {
      display: inline-block;
    }

    .prefers-email-label {
      margin-right: 24px;
    }

    .field,
    .prefers-email,
    .prefers-phone,
    .contact-preference>label,
    .departments>ul>li {
      border-radius: 0.5em;
      border: 1px solid #333;
    }

    .departments>ul>li,
    .contact-preference label {
      padding: 0.8em 1em;
      cursor: pointer;
      width: 220px;
    }

    .departments {
      display: flex;
      justify-content: flex-start;
      gap: 24px;
    }

    .departments>ul {
      list-style-type: none;
      flex: 0 0 30%;
      padding-left: 0;
      padding-right: 0;
    }

    .schedule {
      cursor: pointer;
      margin: 0px auto;
      display: block;
      background-color: green;
      border: 0;
      border-radius: 0.25em;
      color: white;
      padding: 0.5em 1em;
      font-size: 1.25rem;
      font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
        Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
    }
  </style>
</head>

<body>
  <div class="appointment-wrapper">
    <form class="appointment" action="/appointment" method="POST">
      <h1 class="title">Patient Appointment</h1>

      <div class="name">
        <div class="field-control">
          <label for="firstname" class="field-label">First name</label>
          <input value="John" type="text" name="firstname" class="firstname field" />
        </div>

        <div class="field-control">
          <label for="lastname" class="field-label">Last name</label>
          <input value="Doe" type="text" name="lastname" class="lastname field" />
        </div>
      </div>

      <div class="field-group">
        <label class="field-label">Email</label>
        <input value="john@doe.com" type="email" name="email" class="email field" />
        <p class="field-hint">example@example.com</p>
      </div>

      <div class="field-group">
        <label class="field-label">Phone</label>
        <input value="+17182222222" type="tel" name="phone" class="phone field">
        <p class="field-hint">+17182222222</p>
      </div>

      <div class="field-group">
        <label class="field-label">Contact preference</label>
        <div class="contact-preference">
          <label class="prefers-email-label">
            <input checked type="radio" name="contactPreference" class="prefers-email" value="Email">
            Email
          </label>

          <label>
            <input type="radio" name="contactPreference" class="prefers-phone" value="Phone">
            Phone
          </label>
        </div>
      </div>

      <div class="field-group">
        <label for="department">Which department do you want to make an appointment with?</label>
        <div class="departments">
          <ul>
            <li><input checked type="radio" name="department" value="Pediatrics"> Pediatrics</li>
            <li><input type="radio" name="department" value="General Surgery"> General Surgery</li>
          </ul>

          <ul>
            <li><input type="radio" name="department" value="Obstetrics & Gynecology"> Obstetrics &amp; Gynecology</li>
            <li><input type="radio" name="department" value="Neurology"> Neurology</li>
          </ul>

          <ul>
            <li><input type="radio" name="department" value="Orthopedics"> Orthopedics</li>
            <li><input type="radio" name="department" value="Oncology"> Oncology</li>
            <ul>
        </div>
      </div>

      <div class="field-group">
        <label for="time" class="field-label">Time</label>
        <input value="2030-06-01T08:30" type="datetime-local" name="time" class="time field">
      </div>

      <button type="submit" class="schedule">Schedule</button>
    </form>
  </div>

</body>

</html>

Visit http://localhost:3000/appointment.html in your browser and click the Schedule button at the bottom of the page:

This should save the appointment’s details to a `db.json` file created by `lowdb` earlier.

Step 4: Generate PDFs from User Supplied Data

JoyDoc Exporter renders a populated JoyDoc to HTML in a browser context. However, you can take advantage of it outside a browser by adding a JavaScript module like the following to your project.

// generate-pdf.js
import { JSONFilePreset } from 'lowdb/node';
import puppeteer from 'puppeteer';
import { join } from 'path';
import { existsSync, mkdirSync } from 'fs';

async function generatePdfs() {
  const db = await JSONFilePreset('db.json', { joydoc: [], appointment: [] });
  const browser = await puppeteer.launch();
  const page = await browser.newPage();

  await page.addScriptTag({
    url: 'https://cdn.jsdelivr.net/npm/@joyfill/components@latest/dist/joyfill.min.js',
  });

  // Get appointments JoyDoc from the database
  const joydoc = db.data.joydoc.find(
    (doc) => doc.name === 'Patient Appointment'
  );

  if (!existsSync('appointments')) {
    mkdirSync('appointments');
  }

  // Render each appointment in a headless browser and export the page
  // and save it to a PDF file.
  for (let appointment of db.data.appointment) {
    const appointmentJoyDoc = populateDocument(appointment, joydoc);

    console.log(`Generating PDF for ${appointmentJoyDoc.name}`);

    await page.evaluate((appointmentJoyDoc) => {
      const container = document.createElement('div');
      container.id = 'joyfill';
      document.body.appendChild(container);

      document.body.appendChild(container);
      Joyfill.JoyDocExporter(container, {
        doc: appointmentJoyDoc,
        config: { page: { height: 1056, width: 816, padding: 0 } },
      });
    }, appointmentJoyDoc);

    await page.pdf({
      path: join('appointments', `${appointmentJoyDoc.name}.pdf`),
    });

    await page.evaluate(() => {
      document.querySelector('#joyfill').remove();
    });
  }

  await browser.close();
}

function populateDocument(appointment, joydoc) {
  // Include the patient's name in the document's title
  const filledDocument = { ...joydoc };

  // Set the document's name
  filledDocument.name = `${filledDocument.name} - ${appointment.firstname} ${appointment.lastname} - ${appointment.time}`;

  // Set the document's title
  filledDocument.fields[0].value = 'Patient Appointment';

  // Populate other fields of the document
  for (let field of filledDocument.fields) {
    const id = field.identifier;

    if (['contactPreference', 'department'].includes(id)) {
      const option = field.options.find(
        (option) => option.value.trim() === appointment[id].trim()
      );

      field.value = [option._id];
      continue;
    }

    field.value = appointment[id];
  }

  return filledDocument;
}

generatePdfs()
  .then(() => {
    console.log("PDFs saved to 'appointments' successfully");
  })
  .catch((e) => {
    console.log('Failed to generate PDFs', e);
  });

With a bit of hardening and the right sanity checks in place, a setup like the one above, leverages Joyfill’s self-hosted tools and the JoyDoc schema to strike the balance most organizations struggle with. You get full control over where and how data is stored, clear audit trail for compliance teams, and the flexibility engineers need to keep workflows simple. In practice, this means meeting strict regulatory requirements without exposing sensitive information to third-party PDF services or sacrificing usability in the process.

Need to build PDF capabilities inside your SaaS application? Joyfill makes it easy for developers to natively build, embed, and customize form and PDF experiences inside their web and mobile apps.

Integrating PDF generation into Node.js backends: tips & gotchas

John Pagley — Thu, 07 Aug 2025 16:34:10 +0000

Whether you’re building an invoicing system, dynamic reports, or downloadable forms, server-side PDF generation can feel like the “set it and forget it” solution. Compared to rendering PDFs in the browser, doing it on the backend means you have more control over templates, heavier libraries, and the underlying OS. No pop-up blockers, no cross-origin headaches, no client-side processing limits.

But with that flexibility comes new pitfalls: memory-hungry rendering engines, blocking calls that bottleneck your API, bloated serverless deployments, and tricky font or asset management. Even the best open-source libraries can eat CPU or throw cryptic errors when you’re generating large, multi-page PDFs on demand.

This guide breaks down what’s possible, which libraries are worth your time, common performance and security gotchas—and practical tips for running PDF workflows reliably in production.

Why Generate PDFs on the Server?

Client-side PDF generation is handy for small, one-off documents. But once your workflows get bigger—or you need more design precision and data security—moving PDF rendering to your backend just makes sense.

Here’s why many teams choose server-side generation with Node.js:

Consistent output: You’re not at the mercy of different browsers or device quirks. The server generates the same PDF every time.
Full access to assets: Your server can bundle custom fonts, high-resolution images, and templates that might bloat a client-side bundle.
Powerful rendering engines: You can use headless browsers (like Puppeteer) or dedicated Node.js libraries (like PDFKit) that do the heavy lifting without blocking the user’s device.
Data security: Sensitive data never leaves your infrastructure—crucial for things like invoices, medical reports, or contracts.
Better multi-page handling: Complex pagination, tables, and dynamic layouts are often easier to manage with server-side tools and full HTML/CSS rendering.

Of course, this power comes with trade-offs—resource spikes, concurrency headaches, and potential security holes if you don’t sandbox properly. But for many SaaS, finance, or form-heavy apps, it’s the best way to deliver polished, reliable PDFs.

Common Approaches (and Their Trade-Offs)

When you’re generating PDFs on a Node.js backend, you’ll typically run into three main approaches — each with its own strengths, pitfalls, and gotchas.

1. Headless Browser Rendering

What it is:

Tools like Puppeteer or Playwright launch a headless Chromium instance. You feed it your HTML and CSS, it renders a pixel-perfect page in a virtual browser, then prints that page as a PDF.

Why teams use it:

Best fidelity for complex designs.
Supports modern CSS, web fonts, @media print, and interactive layouts.
Mimics what users see in an actual browser — WYSIWYG (What You See Is What You Get).

Gotchas:

Requires bundling a headless browser binary with your server environment.
Cold starts and rendering can be resource-intensive (CPU/memory spikes).
Scaling with many concurrent requests often needs a queue or a serverless function pool to avoid timeouts.

2. Programmatic PDF Generation

What it is:

Libraries like PDFKit or pdf-lib let you construct PDFs line-by-line: adding text, shapes, images, and tables via a JavaScript API.

Why teams use it:

Great for simple reports, receipts, invoices.
No need for a full browser engine — runs lightweight in pure Node.js.
More predictable for static content (e.g., financial statements).

Gotchas:

No “free” rendering from HTML/CSS — you must recreate layout logic manually.
Complex or responsive designs get tricky fast.
Managing fonts, multi-page layout, or internationalization often requires extra work.

3. Hybrid or Third-Party PDF Services

What it is:

Some teams use a hybrid setup: generating a PDF server-side using headless rendering but offloading the actual heavy lifting to a managed service (like Cloudlayer, DocRaptor, or a serverless function with Puppeteer).

Why teams use it:

Handles big spikes in traffic without choking your main Node.js app.
Offloads CPU-hungry rendering tasks to separate infrastructure.
Easier to plug into multi-tenant SaaS platforms.

Gotchas:

Adds cost and an extra dependency.
Potential data privacy considerations — user data must travel to a third-party.
Debugging can get complicated if PDF rendering fails outside your core backend.

There’s no one-size-fits-all. For many teams, the best solution combines elements from all three: fast direct generation for simple PDFs, headless browsers for HTML-heavy documents, and hybrid workflows to handle scaling.

In the next section, we’ll break down how to choose the best library or tool for your use case—so you can match these approaches to real-world developer needs.

Choosing the Right PDF Library or Tool

When you’re picking a PDF generation tool for your Node.js backend, remember: what works in the browser often doesn’t translate to the server. Client-side libraries like html2pdf.js or jsPDF rely on the DOM or <canvas>—things your server simply doesn’t have.

Instead, you’ll choose between:

Headless browser renderers like Puppeteer or Playwright — great for HTML-to-PDF when you want pixel-perfect output that mirrors your frontend.
Pure Node libraries like PDFKit, pdf-lib, or node-pdfmake — ideal for structured, data-driven documents like invoices, reports, or receipts.

Cross-environment note:

A few libraries like pdf-lib do run both in the browser and Node.js, but their use cases shift. In the backend, they’re best for programmatic PDF creation (not rendering HTML). If your workflow is “take HTML → PDF,” you’ll almost always need a headless renderer or server-side template approach.

Here’s a quick practical breakdown:

Library/Tool	Best For	Pros	Cons
`Puppeteer`	HTML/CSS → PDF (high fidelity)	Precise output, supports full CSS, web fonts	Heavy binary, slower cold starts, CPU-intensive
`Playwright`	Similar to `Puppeteer`	Better multi-browser support	Same scaling/resource considerations
`PDFKit`	Invoices, reports, statements	Lightweight, pure Node.js, fast	No HTML/CSS → must build layout manually
`pdf-lib`	Modifying/merging PDFs, low-level creation	Runs client and server, flexible API	No HTML parsing — you handle structure yourself
`node-pdfmake`	Structured, multi-page docs	Declarative JSON syntax, tables, i18n	Limited CSS-like styling, learning curve

Tip: If your Node.js app already generates styled HTML for emails or web views, it often makes sense to reuse that markup with a headless renderer. If your PDFs are more static (e.g., simple receipts, data summaries), then a programmatic tool is lighter and faster.

In the next section, we’ll see how these tools fit into real backend workflows—and which integration patterns make scaling and error handling a lot smoother.

Key Integration Patterns with Node.js

It’s one thing to pick the right PDF generation tool — it’s another to integrate it cleanly into your backend architecture. How you wire up PDF creation affects everything from latency to scalability to your app’s overall stability.

Here are the three most common patterns (and their real-world trade-offs):

1. On-Demand PDF Generation

How it works:

Your Node.js app generates the PDF in real time when the user requests it (e.g., an invoice download). The server holds the process open, streams or buffers the file, then sends it as a response.

When it’s good:

Dynamic content that changes frequently
User-specific reports or receipts
Small- to medium-sized PDFs with low rendering cost

Trade-offs:

Spikes in requests can lead to high CPU/memory usage, especially with headless browsers
Large files or long render times can cause request timeouts
Harder to scale if you can’t offload the work

2. Queued or Deferred Generation

How it works:

Instead of generating PDFs synchronously, you add the task to a queue (e.g., using BullMQ, RabbitMQ, or a serverless function). The PDF is rendered asynchronously, then stored (e.g., in S3 or a database). The user gets a link to download it later.

When it’s good:

Heavy reports with complex layouts or big data sets
Use cases where the PDF isn’t needed instantly (e.g., end-of-day batch reports)
Lets you throttle CPU-heavy rendering

Trade-offs:

Adds latency (users may wait for a download link)
Needs extra logic for job status, retries, and storage cleanup
More moving parts: queues, workers, storage

3. Pre-Generated Templates

How it works:

You generate static PDFs ahead of time (like policy documents or T&Cs) and serve them as static files from your CDN or file storage. Node.js only delivers or updates these when the source data changes.

When it’s good:

PDFs with rarely changing content
High-traffic sites needing instant downloads
Keeps server compute costs low

Trade-offs:

Not suitable for personalized or frequently updated data
Changes require regenerating and invalidating caches

Takeaway: Combine Approaches When It Makes Sense

No matter which pattern you pick, the real goal is to balance speed, user experience, and server health. Many SaaS platforms combine all three: static templates for generic files, real-time generation for dynamic exports, and queued jobs for heavy, data-driven reports.

Next up: performance and scaling tips to keep these workflows reliable at production scale.

Performance & Scalability Considerations

Generating PDFs on a Node.js backend can be deceptively resource-intensive. A single HTML-to-PDF render with a headless browser can spike CPU and memory usage, while multiple concurrent requests can cause queue backlogs, timeouts, or even server crashes if not handled well.

Here’s how teams keep things snappy and production-safe:

Optimize Rendering with Caching

Pre-generate common PDFs: For invoices, receipts, or static agreements that rarely change, store them as static files or cache them in a CDN.
Cache intermediate HTML: If you’re rendering the same template multiple times with minor data changes, cache the compiled HTML to avoid redundant server-side templating work.
Reuse headless browser instances: If you’re using Puppeteer/Playwright, spin up a pool of headless browser instances instead of launching a new one for every request. This cuts down cold start times and keeps resource usage predictable.

Queue Heavy Jobs

For big reports or multi-page documents, don’t block your main request thread. Instead, push jobs to a queue (e.g., using BullMQ or RabbitMQ) and generate the PDF asynchronously.
Notify the user when it’s ready via email, in-app notification, or a download link. This pattern avoids spikes during traffic surges and improves user experience for big exports.

Monitor Memory & CPU

Headless browser rendering is notorious for CPU spikes. Use metrics tools (like PM2, Datadog, or New Relic) to monitor resource usage in real-time.
Set reasonable limits on concurrent PDF jobs. If you’re in serverless, watch out for cold starts and execution timeouts.

Consider Serverless Gotchas

Serverless functions (like AWS Lambda or Vercel functions) are popular for HTML-to-PDF rendering, but they have quirks:

Cold start delays: Spinning up a headless Chromium binary can add several seconds of latency.
Size limits: Bundled binaries for Puppeteer or Playwright can bloat deployment packages.
Timeout risk: Long-running renders (large files or complex pages) may exceed execution limits.

When done right, server-side PDF generation is fast, scalable, and user-friendly. But ignoring these performance details—and overlooking the security implications of handling user data during PDF creation—can sabotage production apps in more ways than one.

Security Risks and Mitigations

When generating PDFs on the backend, especially in multi-tenant or user-facing applications, it’s not just about rendering documents—it’s about doing it securely. PDF generation may seem innocuous, but it introduces several attack surfaces that can be exploited if left unchecked.

1. User Input Injection

If your system accepts raw HTML, text, or URLs from users to include in PDFs, it opens the door to malicious payloads—such as injected JavaScript, malformed content, or links that compromise the rendering environment.

Mitigations:

Sanitize all incoming data, especially if injecting into templates.
Whitelist HTML tags and attributes (or use libraries like sanitize-html).
Escape user content before insertion into document renderers.

2. Exposing Internal Resources via Headless Browsers

If using tools like Puppeteer or Playwright, users could submit URLs or HTML that reference internal services, environment variables, or localhost APIs—turning your PDF service into an internal scanner.

Mitigations:

Set strict -no-sandbox or -disable-web-security flags with caution.
Use page.setRequestInterception() to block non-whitelisted domains.
Run rendering in a secure containerized environment (e.g., with firejail or Docker).

3. Denial of Service (DoS) Through Large or Complex Inputs

Unbounded or deeply nested HTML can crash headless browsers or memory-starve your Node.js process. An attacker could submit oversized images, recursive DOM trees, or massive tables to overload rendering.

Mitigations:

Set maximum input size or DOM depth.
Use a timeout or watchdog to kill long-running renders.
Pre-validate templates or throttle expensive jobs using a queue.

4. Temporary File Exposure

Some tools render to disk before serving the final PDF. If not properly handled, this could leak files or expose a race condition where one user accesses another’s output.

Mitigations:

Use unique file names and directories per request.
Immediately delete temp files after serving or use in-memory buffers.
Never expose file paths in responses or logs.

5. Third-Party API or Font Fetching

If your HTML includes links to Google Fonts, external stylesheets, or CDNs, the rendering engine may fetch those over the internet—potentially leaking document content or metadata.

Mitigations:

Self-host critical fonts and stylesheets.
Preload all required assets to avoid runtime fetching.
Use a CSP (Content Security Policy) during rendering where possible.

Security isn’t just about locking the door—it’s about knowing where your walls, windows, and crawlspaces are. In the next section, we’ll look at real-world gotchas that can trip up even experienced teams.

Practical Gotchas Developers Run Into

Even with the right libraries and architecture in place, PDF generation in Node.js backends is still full of edge cases and invisible traps. These aren’t theoretical—they’re the kinds of issues that derail timelines and frustrate teams mid-sprint.

Headless Browser Rendering Can Be… Moody

Tools like Puppeteer and Playwright are fantastic—until they’re not. Differences in local vs. production rendering, flaky CI (Continuous Integration) behavior, or subtle layout shifts due to missing fonts can all appear seemingly at random.

What to watch for:

Rendering differences between local development and Dockerized production (especially around fonts, screen resolution, or environment flags).
Print media queries (@media print) not behaving as expected in headless mode.
Failing renders due to invisible timeouts or blocked resource loading (e.g., missing external CSS or JS).

Fixes:

Test your rendering pipeline in an environment that mirrors production.
Preload all fonts and styles locally (don’t rely on CDNs).
Use Puppeteer’s waitUntil: 'networkidle0' or page.emulateMedia() correctly before calling .pdf().

Async Logic Inside Templates

Templating engines (like EJS, Handlebars, or Pug) often support dynamic data injection. But combining that with asynchronous data fetching (e.g., API calls, DB queries) can produce timing bugs, partial renders, or even blank PDFs if the data hasn’t resolved in time.

What to watch for:

PDF output missing data that exists in logs.
Pages generated with placeholder values (e.g., {{name}}) still present.
Race conditions when parallelizing PDF jobs.

Fixes:

Resolve all data before rendering templates.
Wrap async logic in Promise.all() or data loaders outside the rendering phase.
Use render pipelines that fail early if data is incomplete.

Long Renders Can Crash or Time Out

You won’t notice this on small test PDFs—but once your app hits production with multi-page reports, high-resolution charts, or dozens of invoices in a single batch, memory usage skyrockets.

What to watch for:

Out-of-memory errors from Node.js or Puppeteer.
Timeout failures in cloud functions (e.g., AWS Lambda, Vercel Functions).
Huge PDFs that download slowly or crash PDF viewers.

Fixes:

Cap the number of pages or items per document.
Use chunked rendering (e.g., 10 invoices per PDF).
For serverless: bump function memory/timeout or queue jobs for async processing.

Version Drift and Inconsistent Output

PDF libraries often have breaking changes or behavior shifts between versions. Even a minor update to Puppeteer or pdf-lib can alter line spacing, page dimensions, or font rendering.

What to watch for:

“Why does this look different from last week?”
“This PDF works on staging but breaks on production.”
“The button moved. Again.”

Fixes:

Lock down versions tightly in package.json.
Test visual output regularly in CI with diff tools (e.g., pixelmatch, Resemble.js).
Avoid upgrading rendering tools casually—treat them like front-end rendering engines.

PDF generation is powerful, but fragile. In the next section, we’ll look at when it makes sense to offload this task entirely to managed services—and how to decide based on your app’s scale and needs.

When to Offload to a Managed Service?

Not every team wants—or needs—to own the full complexity of PDF generation. In many cases, offloading the heavy lifting to a managed service or API can dramatically reduce development time and operational overhead.

Why Offload?

Infrastructure Simplification: No need to install and maintain headless browsers, handle font embedding, or debug rendering quirks across OS environments.
Scalability Without Headaches: Services like Joyfill offer infrastructure that automatically scales to meet demand—even during traffic spikes.
Speed to Market: You focus on templating and business logic, not browser automation or PDF layout engines.
Cross-Platform Consistency: Output is typically generated in isolated, controlled environments—ensuring predictable results regardless of where your app runs.

When It Makes Sense

Managed PDF services are a great fit when:

You need pixel-perfect rendering with minimal setup.
You’re dealing with multi-tenant SaaS workloads and want to decouple PDF generation from your main Node.js app.
You require audit trails, form intelligence, or advanced metadata in your documents.
You’d rather avoid the churn of maintaining browser dependencies and system-level font rendering.

Gotchas to Consider

Cost at Scale: Most services charge per document or usage tier. If you're generating tens of thousands of PDFs, costs can balloon quickly.
Data Privacy Concerns: Sensitive data is sent to a third-party provider. Ensure compliance with regulations like GDPR, HIPAA, or SOC 2 if applicable.

Takeaway: If your core business isn't PDF generation, managed services can offer significant leverage—freeing your team to focus on product, not PDF rendering quirks. But be mindful of vendor lock-in, compliance, and long-term cost as your workload grows.

Final Thoughts: Build Smart, Ship Confidently

Generating PDFs on the server with Node.js isn’t hard—but doing it well, at scale, and without surprises takes planning.

You have a growing ecosystem of tools to choose from. Some give you pixel-perfect HTML rendering. Others let you build reports line by line with full control. And a few take the entire burden off your infrastructure with managed APIs. Each path has trade-offs—your best choice depends on the demands of your product and users.

To wrap up:

If you need total control over layout and styling, headless browser tools like Puppeteer or Playwright give you full HTML-to-PDF rendering power.
If you’re building template-driven documents like invoices or receipts, libraries like pdf-lib or PDFKit work well for predictable layouts.
If your app needs to scale across many tenants or workloads, consider using queues, caching, and async workflows to manage performance.
If you want to offload PDF rendering entirely, managed services like Joyfill provide a fast path to production with audit trails, field logic, and scalable infrastructure.

No matter what you choose, here’s the golden rule: don’t treat PDF rendering as an afterthought. It’s part of your product experience. If a user clicks “Download” and sees a blurry, broken, or misaligned PDF, it’s your brand that takes the hit.

Start with clarity. Test early. Scale intentionally. That’s how you build PDF workflows that won’t let your product—or your users—down.

Need to build PDF capabilities inside your SaaS application? Joyfill makes it easy for developers to natively build and embed form and PDF experiences inside their own SaaS applications.

Creating PDFs from HTML + CSS in JavaScript: What actually works

John Pagley — Thu, 31 Jul 2025 20:41:00 +0000

Developers often assume that generating a PDF from styled HTML is as simple as passing a DOM node to a library and hitting “download.” In reality, converting the dynamic, flowing nature of HTML and CSS into a static, print-ready PDF—all in the browser—comes with unexpected challenges.

From missing CSS features to blurry image rendering and broken page breaks, browser-based HTML-to-PDF conversion is a minefield of workarounds and limitations. This article explores what actually works, which libraries are worth your time, and how to approach client-side PDF generation with realistic expectations.

Why Generating PDFs from HTML Is a Developer Headache

On the surface, it sounds simple: take the styled HTML your app already renders and save it as a PDF. But the moment developers try to do this client-side, reality hits hard.

PDFs and HTML were never meant to speak the same language. HTML is flexible, dynamic, and flows to fit different screens and interactions. PDFs, on the other hand, are static, fixed-layout documents meant for precise print output. The conversion between the two isn’t just a technical challenge—it’s a conceptual mismatch.

What complicates this further is that the tools available for browser-based PDF generation are limited in how they interpret and render CSS. Many modern layout features—like Flexbox, Grid, and media queries—are poorly supported or ignored altogether. Font handling, background images, page breaks, and z-index stacking are also common points of failure.

And while server-side solutions like Puppeteer can generate near-perfect replicas by rendering a real browser environment, they come with infrastructure costs and can’t run purely client-side. For developers looking to stay serverless, lightweight, and private, that option is often off the table.

The end result? You might spend more time fighting CSS quirks and rendering bugs than actually generating documents.

What Makes HTML-to-PDF So Hard?

Turning HTML into a PDF may seem like a basic export task—but under the hood, it’s one of the most technically frustrating things a frontend developer can attempt.

Here’s why:

1. HTML and PDF Use Different Layout Models

HTML is fluid. It reflows content based on screen size, font metrics, and responsive breakpoints. PDFs are rigid. Every element must be positioned precisely on a fixed-size canvas.

That means features we rely on—like width: 100%, display: flex, or media queries—don’t naturally translate. PDF engines require hard numbers: exact X/Y positions, fixed widths, and explicit page breaks.

2. CSS Rendering Support Is Incomplete

Most client-side HTML-to-PDF tools don’t run a full browser engine. Instead, they simulate the DOM and paint elements manually onto a canvas or PDF buffer.

The catch? They only support a subset of CSS:

Complex layouts (e.g. CSS Grid, position: sticky) are unreliable.
Pseudo-elements (::before, ::after) often don’t render.
@media print styles are usually ignored.
External stylesheets or dynamically injected styles may be skipped unless carefully inlined.

3. Text and Fonts Get Lost in Translation

Some tools rasterize HTML into an image before embedding it in a PDF. That’s fast and visually consistent—but comes at a cost:

Text becomes non-selectable and non-searchable.
Font fidelity may suffer.
File sizes can balloon due to high-res image embedding.

Other tools preserve vector text, but require you to manually embed fonts or convert styling into low-level primitives.

4. Page Breaks and Multi-Page Layouts Are Painful

The browser scrolls infinitely. PDFs don’t.

When converting HTML content into multi-page PDFs, you often need to:

Calculate when a section should break
Prevent elements from splitting across pages
Dynamically insert headers and footers

Even tools that offer page break helpers struggle when layout becomes dynamic or deeply nested.

The short version? HTML and PDF speak different dialects, and getting them to communicate smoothly—especially in a browser—is far more nuanced than it first appears.

The Client-Side Toolkit: What’s Actually Available?

If you’ve ever typed “HTML to PDF JavaScript” into a search engine, you know the sea of libraries can be overwhelming. But in reality, only a few libraries truly generate PDFs in the browser—and most rely on hidden helpers behind the scenes.

When you look closely, the client-side ecosystem breaks into two groups:

Primary PDF Libraries: These handle end-to-end HTML-to-PDF conversion (or offer tools to help you build PDFs programmatically).
Supporting Utilities: These convert DOM elements into images or canvas elements—but cannot generate PDFs by themselves.

Let’s break them down.

Primary PDF Libraries

These are the libraries you’ll actually use to create PDFs in the browser.

`html2pdf.js` (wraps `html2canvas` + `jsPDF`)

Type: Image-based PDF generator
How it works: Takes a screenshot of an HTML element (html2canvas) and embeds it into a PDF (jsPDF)
Pros:
- Easy to use, minimal setup
- Great for simple, static content like certificates
- Fully client-side
Cons:
- Renders content as an image (text is not selectable)
- Limited support for CSS (especially modern layouts)
- Fonts may look blurry at print resolution

`jsPDF` (with `.html()` method)

Type: DOM-based capture (with fallback to html2canvas)
How it works: Attempts to parse the DOM and build a PDF, but relies on html2canvas for styled content
Pros:
- Lightweight, programmatic control
- Works for basic HTML with inline styles
Cons:
- Poor support for external stylesheets
- Output is often distorted or oversized
- Difficult to use for real-world styling

`pdfmake` (with `html-to-pdfmake` helper)

Type: Structured, declarative PDF generator
How it works: Uses a JSON schema to define layout; html-to-pdfmake helps convert basic HTML into this format
Pros:
- Outputs real, selectable text (vector rendering)
- Strong support for tables, layout, multi-page content
- Great for invoices, reports, form-driven documents
Cons:
- Steeper learning curve
- Limited HTML and CSS compatibility
- Styling done via config, not DOM or CSS

Supporting Utilities (Not PDF Generators)

These tools help render HTML to canvas or image formats, but do not generate PDFs on their own.

`html2canvas`

Type: DOM ➝ Canvas renderer
How it works: Converts a DOM element into a <canvas> image (used internally by html2pdf.js and others)
Pros:
- Easy to use for screenshot capture
- Works with most basic HTML/CSS
Cons:
- Incomplete CSS support (e.g., Grid/Flex)
- Cannot generate PDFs directly
- CORS issues with external images

`dom-to-image`

Type: DOM ➝ Image (PNG, SVG)
How it works: Converts a DOM node to a downloadable image
Pros:
- Good for image previews or animations
- Supports SVG output for crisp visuals
Cons:
- Doesn’t support PDF export
- Suffers similar limitations as html2canvas with styling

TL;DR: Two Camps, Two Trade-Offs

Tool	Type	Output Format	Selectable Text	Best Use Case
`html2pdf.js`	PDF Library	Image in PDF	❌	Quick, styled exports
`jsPDF.html()`	PDF Library	Image/HTML	❌	Basic DOM snapshots
`pdfmake`	PDF Library	Vector PDF	✅	Structured documents
`html2canvas`	Utility (screenshot)	Canvas/Image	❌	Pre-render content for PDF
`dom-to-image`	Utility (screenshot)	Image (PNG/SVG)	❌	Export styled visuals as images

But before diving into styling challenges, let’s take a closer look at the rendering strategies themselves—because how content is rendered shapes everything else.

Vector vs. Raster Rendering: Why It Matters

Not all HTML-to-PDF tools are created equal—and the difference often boils down to how they render content: as vectors or raster images.

Raster-Based Rendering

Libraries like html2canvas (and tools built on it, such as html2pdf.js) take a screenshot-style approach. They render your HTML as a bitmap image, then embed that image inside a PDF. Think of it like printing a web page and scanning it.

Pros:

Relatively easy to implement
Faithful visual capture of complex layouts (what you see is what you get)

Cons:

Text is not selectable or searchable
Quality suffers when zoomed or printed (blurry or pixelated)
File sizes can be large, especially with images or long pages

Vector-Based Rendering

Libraries like pdfmake use vector instructions to construct each part of the PDF—from text to shapes to tables. You’re not capturing pixels—you’re describing structure.

Pros:

Text is crisp, searchable, and scalable
Smaller file sizes
Output quality is more professional and print-ready

Cons:

Requires a more abstract, programmatic setup
Doesn’t directly mirror your existing HTML/CSS—layouts must be rebuilt using JavaScript objects

Choosing between these two rendering models isn’t just a technical detail—it directly affects the usability and quality of your PDF output. If you need visual fidelity, raster might suffice. If you need searchability and print precision, go vector.

In the next section, we’ll break down how CSS plays into this—and why styling is often where things fall apart.

CSS Support and Styling Constraints

Even the most promising HTML-to-PDF tools can falter when faced with real-world CSS. Why? Because browsers and PDF engines speak very different layout languages—and not all styling features translate cleanly.

Here’s what developers typically run into:

Limited CSS Feature Support

Modern Layouts: Flexbox and Grid often render inconsistently—or not at all—especially in raster-based tools like html2canvas. In structure-based tools like pdfmake, layout must be recreated using its custom schema.
External Stylesheets: Tools like jsPDF().html() frequently ignore external stylesheets—unless those styles are inline or already computed in the DOM. This often leads to layout shifts or broken formatting.
Media Queries: Libraries don’t honor @media print rules, meaning dark mode or responsive styles might sneak into exported PDFs unintentionally.
Pseudo-elements and Transforms: ::before, ::after, transform, and z-index often don’t render—or render incorrectly—resulting in misplaced or missing content.

Styling Hacks Are Often Required

To work around these issues, developers often need to:

Inline all critical styles and remove reliance on external CSS
Manually restructure layouts that previously relied on flex or grid
Create dedicated “print views” stripped of animations, interactive elements, or dark mode themes
Resize and reflow content to fit standard PDF dimensions and prevent overflow or cut-off sections

These band-aids help—but they result in duplicated styling logic and make maintenance harder.

When Rendering Tools Don’t Think Like Browsers

We found that jsPDF().html()—despite promising vector-based, searchable text—can render content at incorrect scales, especially when layout widths exceed default PDF page sizes. In our tests, even a modest table layout spilled into multiple pages unless we manually tweaked dimensions or switched to landscape mode.

Meanwhile, pdfmake's helper (html-to-pdfmake) preserves structure, but strips most CSS nuance. Alignment, spacing, and styling fidelity often degrade unless redefined using its custom syntax.

Image-Based Rendering Has Its Own Drawbacks

For tools like html2canvas or html2pdf.js, the rendering process creates an image—not actual DOM content. That introduces:

Blurry fonts or jagged text, especially on high-DPI screens
Non-selectable and non-searchable output
No real layout intelligence—just a screenshot
Font fallbacks if external fonts aren’t accessible or embedded

These tools work best for simple, single-page documents where appearance matters more than precision.

In the next section, we’ll look at how these limitations play out in real examples—so you can see what actually works, what breaks, and what’s worth fixing.

Real-World Examples: What Works (and What Doesn’t)

So how do these tools behave when tested in the wild? Below are simplified examples that reflect common developer use cases—along with what actually happens when you run the code in a real browser.

Example 1: `html2pdf.js` for a Simple Certificate

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>html2pdf.js Example - Certificate</title>
  <style>
    #certificate {
      width: 600px;
      padding: 40px;
      margin: 30px auto;
      border: 5px double #444;
      text-align: center;
      font-family: 'Georgia', serif;
      background-color: #fdfdfd;
      color: #222;
    }
    #certificate h2 {
      margin-bottom: 10px;
      font-size: 28px;
    }
    #certificate p {
      margin: 8px 0;
      font-size: 16px;
    }
    #download-btn {
      display: block;
      margin: 20px auto;
      padding: 10px 20px;
      font-size: 16px;
      cursor: pointer;
    }
  </style>
</head>
<body>
  <div id="certificate">
    <h2>Certificate of Completion</h2>
    <p>This certifies that</p>
    <h3><strong>Jane Doe</strong></h3>
    <p>has successfully completed the JavaScript PDF Generation Course</p>
    <p><em>Dated: June 14, 2025</em></p>
  </div>

  <button id="download-btn">Download as PDF</button>

  <!-- Load html2pdf.js and dependencies from CDN -->
  <script src="<https://cdnjs.cloudflare.com/ajax/libs/html2pdf.js/0.10.1/html2pdf.bundle.min.js>"></script>
  <script>
    document.getElementById("download-btn").addEventListener("click", () => {
      const element = document.getElementById("certificate");
      const opt = {
        margin:       0,
        filename:     'certificate.pdf',
        image:        { type: 'jpeg', quality: 0.98 },
        html2canvas:  { scale: 2 },
        jsPDF:        { unit: 'pt', format: 'letter', orientation: 'portrait' }
      };

      html2pdf().set(opt).from(element).save();
    });
  </script>
</body>
</html>

What works:

Very fast to implement—just point it at an HTML node
Preserves most on-screen styling, including fonts, colors, and layout
Great for simple, static exports like certificates, badges, or receipts

What breaks down:

Text is not selectable or searchable—it’s just a screenshot
Output can appear blurry on high-DPI or Retina screens
Doesn’t handle long or paginated content well—everything gets flattened into a single image, even if it spans multiple pages

Example 2: `jsPDF().html()` with Styled Content

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>jsPDF HTML to PDF Example</title>
  <style>
    body {
      font-family: sans-serif;
      background: #f9f9f9;
      padding: 2rem;
    }

    #receipt {
      width: 800px;
      margin: 0 auto;
      background: #fff;
      padding: 24px;
      border: 1px solid #ccc;
      box-shadow: 0 0 6px rgba(0, 0, 0, 0.1);
    }

    h2 {
      text-align: center;
      margin-bottom: 1rem;
    }

    table {
      width: 100%;
      border-collapse: collapse;
      margin-top: 1rem;
    }

    th, td {
      border: 1px solid #999;
      padding: 10px;
      text-align: left;
    }

    tfoot td {
      font-weight: bold;
    }

    .button-container {
      text-align: center;
      margin-top: 2rem;
    }

    button {
      padding: 10px 20px;
      font-size: 1rem;
      background: #2d72d9;
      color: white;
      border: none;
      cursor: pointer;
    }

    button:hover {
      background: #1b4da2;
    }
  </style>
</head>
<body>
  <div id="receipt">
    <h2>Sales Receipt</h2>
    <p><strong>Date:</strong> June 14, 2025</p>
    <p><strong>Customer:</strong> Jane Doe</p>

    <table>
      <thead>
        <tr>
          <th>Item</th>
          <th>Qty</th>
          <th>Price</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>Notebook</td>
          <td>2</td>
          <td>$5.00</td>
        </tr>
        <tr>
          <td>Pens (Pack of 5)</td>
          <td>1</td>
          <td>$3.50</td>
        </tr>
        <tr>
          <td>Binder</td>
          <td>1</td>
          <td>$6.00</td>
        </tr>
      </tbody>
      <tfoot>
        <tr>
          <td colspan="2">Total</td>
          <td>$14.50</td>
        </tr>
      </tfoot>
    </table>
  </div>

  <div class="button-container">
    <button onclick="generatePDF()">Download PDF</button>
  </div>

  <script src="<https://cdnjs.cloudflare.com/ajax/libs/jspdf/2.5.1/jspdf.umd.min.js>"></script>
  <script src="<https://cdnjs.cloudflare.com/ajax/libs/html2canvas/1.4.1/html2canvas.min.js>"></script>
  <script>
    async function generatePDF() {
      const { jsPDF } = window.jspdf;

      const doc = new jsPDF({
        unit: "px",
        format: "a4",
        hotfixes: ["px_scaling"]
      });

      const element = document.getElementById("receipt");

      await doc.html(element, {
        html2canvas: {
          scale: 1,
          useCORS: true
        },
        callback: function (doc) {
          doc.save("receipt.pdf");
        }
      });
    }
  </script>
</body>
</html>

What works:

Uses the actual DOM to generate content—no canvas screenshot required
Text remains searchable and selectable in the PDF (vector-based output)
Can handle basic inline styles (colors, fonts, spacing)
Runs entirely in the browser—no server dependency

Note: jsPDF produces vector-based output when using .html() directly. However, if paired with html2canvas (as some older examples do), the rendering becomes rasterized and text is no longer selectable.

What breaks down:

External stylesheets are ignored—only inline or computed styles are applied
Layout may break or overflow, especially with fixed-width containers (e.g., 800px tables in portrait mode)
Responsive designs don’t translate well—PDFs have fixed dimensions, but HTML layouts often assume fluid widths
Layout quirks include unexpected zoom, oversized elements, or extra pages—especially if widths and padding aren’t tightly constrained
No built-in support for page breaks—content that overflows often gets cut off without warning

In our testing, even a modest invoice-style layout ended up overflowing the page horizontally in portrait mode. While switching to landscape orientation can fix this, it highlights a deeper issue: jsPDF().html() doesn’t “understand” layout context the way a browser does.

This tool can be useful—but it requires careful content sizing and style isolation to avoid unexpected breakage. It’s not a plug-and-play option for fully styled web pages.

Example 3: `pdfmake` with `html-to-pdfmake` Helper

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>pdfmake Invoice Example</title>
  <style>
    #invoice {
      max-width: 600px;
      margin: 40px auto;
      padding: 20px;
      font-family: Arial, sans-serif;
      border: 1px solid #ccc;
    }
    h2 {
      text-align: center;
      margin-bottom: 20px;
    }
    table {
      width: 100%;
      border-collapse: collapse;
      margin-top: 10px;
    }
    th, td {
      border: 1px solid #999;
      padding: 8px;
      text-align: left;
    }
    th {
      background-color: #f0f0f0;
    }
    .total {
      font-weight: bold;
      text-align: right;
    }
    button {
      display: block;
      margin: 30px auto;
      padding: 10px 20px;
      font-size: 16px;
    }
  </style>
</head>
<body>

<div id="invoice">
  <h2>Invoice</h2>
  <p><strong>Date:</strong> 2025-06-14</p>
  <p><strong>Customer:</strong> Jane Doe</p>
  <table>
    <thead>
      <tr>
        <th>Item</th>
        <th>Qty</th>
        <th>Price</th>
        <th>Total</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Widget A</td>
        <td>2</td>
        <td>$10.00</td>
        <td>$20.00</td>
      </tr>
      <tr>
        <td>Widget B</td>
        <td>1</td>
        <td>$25.00</td>
        <td>$25.00</td>
      </tr>
    </tbody>
  </table>
  <p class="total">Grand Total: $45.00</p>
</div>

<button onclick="downloadPDF()">Download PDF</button>

<!-- Dependencies -->
<script src="<https://cdnjs.cloudflare.com/ajax/libs/pdfmake/0.2.7/pdfmake.min.js>"></script>
<script src="<https://cdnjs.cloudflare.com/ajax/libs/pdfmake/0.2.7/vfs_fonts.js>"></script>
<script src="<https://cdn.jsdelivr.net/npm/html-to-pdfmake/browser.js>"></script>

<script>
  function downloadPDF() {
    const invoiceElement = document.getElementById("invoice");
    const html = htmlToPdfmake(invoiceElement.innerHTML, { window: window });

    const docDefinition = {
      content: html,
      defaultStyle: {
        fontSize: 11
      }
    };

    pdfMake.createPdf(docDefinition).download("invoice.pdf");
  }
</script>

</body>
</html>

What works:

Produces real vector-based PDFs with selectable, searchable text
Handles tables and structured layouts with clarity and precision
Maintains semantic structure better than image-based tools

What breaks down:

Ignores most CSS styling beyond color, font weight, and basic text properties
Alignment styles (like text-align: center or right) often fail to translate—and may default to left alignment in the output
More complex layouts typically need to be rebuilt using pdfmake’s schema for accurate results

Takeaway

Each tool has practical value—but only within its sweet spot:

For static layouts with minimal styling, image-based tools like html2pdf.js offer a quick win.
For searchable text and structured layouts, libraries like pdfmake—with helper utilities—are more reliable.
But if your needs go deeper, consider hybrid workflows or server-side rendering (covered in a later section).

In the next section, we’ll look at browser and mobile quirks that can impact even well-crafted solutions.

Browser Limitations and Mobile Quirks

Even if your HTML-to-PDF setup works perfectly on desktop, browser-specific quirks—especially on mobile—can quickly derail your output. These aren’t just edge cases; they’re common gotchas that affect real users—and we ran into several of them during testing.

Canvas Size Limits (iOS Safari Especially)

If you're using tools like html2canvas or html2pdf.js, you're relying on the browser’s ability to render a full document as a <canvas>. But mobile browsers, especially iOS Safari, impose hard limits on:

Canvas height or pixel area: If your content exceeds the limit, the canvas (and therefore your PDF) may render blank or partially cut off.
Memory usage: Large canvas operations can trigger performance throttling or tab crashes—especially on older phones or tablets.

Workaround: Split large documents into smaller chunks and paginate manually, or avoid canvas-based tools altogether for long reports.

Viewport Assumptions and DOM Rendering Quirks

Libraries like jsPDF().html() rely on computed layout dimensions—but they don’t always interpret the DOM the way a browser does. During our testing, we saw:

Overflows and cut-off elements when fixed-width content (like 800px tables) didn’t fit inside default portrait dimensions.
Zoomed or scaled-up rendering caused by poor handling of parent containers, body margins, or default zoom levels.
Layout shifts between browsers due to font fallback, differing box models, or unsupported inline styles.

Tip: Manually resize or constrain layout widths before export, and test across multiple viewports (portrait, landscape) to reduce surprises.

Lazy Loading, CORS, and Missing Images

Many modern sites use lazy-loaded images (loading="lazy") or fetch assets from CDNs. These features don’t always play well with client-side PDF tools:

Lazy-loaded images may not load in time before the canvas or DOM snapshot occurs—leading to missing visuals.
Cross-origin (CORS) images can "taint" the canvas, preventing rendering or crashing the PDF step.
CSS-based images, masks, or background gradients are inconsistently supported, especially in raster-based tools.

Workaround: Preload images, disable lazy loading temporarily, and ensure proper CORS headers are set if fetching external assets.

Download Behavior Varies by Browser

Even once you’ve generated a PDF blob, getting it to download correctly isn’t guaranteed:

iOS Safari often refuses to download PDFs directly to the file system—it opens them in a new tab instead.
Pop-up blockers can interfere with window.open() or automatic triggers from JavaScript libraries.
Print preview flows (like pdfMake.print()) behave inconsistently across platforms.

Tip: Always provide a visible fallback (e.g. a download button with target="_blank" or download attributes) for cross-browser stability.

Browser behavior isn’t always in your control—but understanding these quirks early on can save you hours of debugging. In the next section, we’ll zoom out to look at the bigger picture: when client-side isn’t the best tool for the job.

When to Use a Hybrid or Server-Side Approach

Client-side tools are impressive—but they can’t do everything. As your documents grow in complexity, length, or styling precision, it may be time to offload rendering to a server or headless browser.

Signs You’ve Hit the Client-Side Ceiling

You might want to consider a hybrid or server-side approach if you encounter:

Consistent rendering issues with complex layouts, even after workarounds
High-fidelity branding requirements (e.g., pixel-perfect PDF output)
Very large documents that crash the browser or render incomplete on mobile
Custom fonts and media-heavy content that bloats the bundle or causes CORS issues
Dynamic, paginated content (e.g., long tables or multi-page reports)

Client-side solutions can struggle under these demands—not because they’re bad, but because browsers aren’t PDF engines.

What Server-Side Rendering Unlocks

Tools like Puppeteer, Playwright, or commercial services (like DocRaptor or Cloudlayer.io) use a real browser engine to generate your PDF—just like printing a webpage:

100% CSS support, including @media print, Flexbox, Grid, and even animations
Accurate pagination across multi-page layouts
Embedded web fonts and high-resolution images
Improved accessibility and selectable/searchable text
Better internationalization (e.g., RTL or multi-language content)

You send HTML/CSS to the server, render it headlessly, and return the final PDF to the client. Yes, it adds backend complexity—but it drastically improves rendering fidelity and cross-browser reliability.

Hybrid Models: Best of Both Worlds

Don’t want a full backend stack just for PDFs? Try a hybrid model:

Render layout client-side → send HTML snapshot or sanitized DOM to a backend PDF microservice
Or use headless rendering only when needed (e.g., fallback for unsupported devices)

Many frontend teams now combine client-side speed with server-side precision—reserving the heavy lifting for special cases.

In short, don’t feel locked into one approach. The best PDF stack is the one that meets your users’ needs without adding unnecessary pain for your team.

Up next: when it's time to stop fiddling with low-level tools altogether—and lean on higher-level platforms like Joyfill.

When (and Why) to Use a High-Level Solution Like Joyfill

As you’ve seen, client-side tools for HTML-to-PDF can do a lot—but they all operate within the limits of the browser’s rendering capabilities. If you find yourself wrestling with CSS quirks, performance trade-offs, or multi-page layout hacks, it might be time to step back and ask:

Should I keep pushing these tools—or is there a better abstraction?

High-level PDF generation platforms (like Joyfill) rethink the problem entirely. Rather than converting rendered HTML into a static PDF, they start from structured data and business logic—then generate forms and PDFs from that source of truth.

This approach is particularly useful when your use case includes:

Dynamic, form-driven documents with logic (e.g., field visibility, validation)
JSON data structures that need to map cleanly into PDFs
Teams maintaining reusable, versioned document templates
SaaS applications embedding fillable forms or submission workflows
Cross-platform rendering consistency (desktop, mobile, web)

These platforms aren't just about fidelity—they're about maintainability, scale, and developer velocity. By separating layout, logic, and data, high-level tools let you ship complex PDF experiences faster—and with fewer moving parts to debug later.

In the final section, we’ll recap the landscape and help you decide what tool fits your team, your users, and your document stack.

Final Thoughts: Pick the Right Tool, Then Ship

Turning HTML and CSS into PDFs in the browser sounds simple—until you try it. What seems like a straightforward task quickly runs into the reality of rendering mismatches, styling inconsistencies, and platform quirks.

Raster-based tools like html2pdf.js are fast and convenient, but render your content as images—resulting in non-selectable text, blurry visuals, and poor scaling.
DOM-based tools like jsPDF().html() offer vector output, but struggle with CSS fidelity, external stylesheets, and responsive layouts.
Declarative tools like pdfmake prioritize structure and searchability, but force you to translate HTML into a custom object format.
Hybrid or server-side solutions (e.g. Puppeteer) unlock full fidelity, but introduce infrastructure, security, and cost considerations.

There’s no silver bullet. But there is a best-fit solution—depending on your needs:

Need a quick, informal export? Raster tools are fine.
Need selectable text and layout precision? Go vector.
Need consistent, scalable forms inside a web app? Consider high-level platforms.

Then prototype. Test in your browser. Stress the limits. And when those limits start costing you time and complexity?

If you're building PDF experiences inside your own SaaS application, Joyfill makes it easy to go beyond the browser—offering a data-driven, form-aware platform for scalable document generation.

Pick your tools wisely. Then ship confidently.

The untold story behind the popular open-source PDF library—react-pdf

John Pagley — Thu, 17 Jul 2025 21:46:02 +0000

In the ever-evolving world of front-end development, few tools have resonated with developers as profoundly as React-PDF. In a recent conversation with Joyfill co-founder John, we had the pleasure of diving into the story behind the library with its creator, Diego Muracciole—a developer whose blend of curiosity, experimentation, and open-source spirit helped turn a side project into a widely used solution across the React ecosystem.

Watch the full conversation here: The untold story behind react-pdf with Diego Muracciole

The Birth of React-PDF: From Terminal to Print

Diego’s journey began far from Silicon Valley, in Uruguay, where he worked at a software agency. With a deep interest in front-end technologies and a keen eye on React’s evolution, Diego explored its potential beyond the browser. He had already built react-log, a quirky yet technically impressive library for rendering React components in the terminal, when he started thinking about new use cases.

The idea for React-PDF came as he was preparing for a local meetup. “I was just looking for something fun to build,” he says. What began as a proof of concept quickly grew into a serious project. The key idea? Use React not just for rendering DOM or native views—but for generating clean, structured, and reusable PDF documents.

“React is perfect for that because of JSX,” Diego explains, “which is basically HTML syntax, allowing nesting elements, creating components, and reusing them.”

This alignment with React’s core philosophy—learn once, write anywhere—meant developers could bring their existing skills to generate documents for invoices, reports, or form submissions with minimal friction. The ability to pull in dynamic data from APIs and still maintain a polished document layout was a game-changer.

Scaling Open Source: Work, Luck, and the Unexpected

While many look to React-PDF today as a robust solution for PDF generation, Diego is candid about the project’s growth: “I always say it was a bit of luck,” he laughs, acknowledging that while luck played a role, consistent effort and community engagement were essential.

The project matured during Diego’s time at Scale AI. Over time, contributions from a growing community of developers helped React-PDF evolve into a go-to tool for modern document generation.

Looking Ahead: AI and Open Source Maintenance

As with every modern developer, the question of AI came up. While Diego hasn’t embedded AI directly into React-PDF, he’s open to using it for maintaining the library, managing issues, and staying responsive to user feedback. “I didn’t use any agents to help me fix issues,” he notes, “but AI might be helpful for keeping up with work and responding to the community.”

This pragmatic view reflects an ongoing challenge for open source maintainers: scaling their time as adoption grows. Tools like GitHub Copilot and AI-based bots are beginning to play a role in easing that burden—something Diego is keeping a close eye on.

A Shoutout to Contributors

Diego also gave credit where credit is due, recognizing several contributors who’ve helped shape the library. Their work and collaboration have helped keep the project alive, stable, and ever-improving.

Final Thoughts

The story of React-PDF is one many developers can relate to: a mix of curiosity, experimentation, and building for the sheer fun of it. But it’s also a reminder of the power of open source—how a side project shared with the world can become a core tool in thousands of products.

As Diego continues to explore new technologies and maybe even brings AI into the fold, React-PDF stands as a testament to what happens when you follow your technical interests and share them freely.

Whether you’re building invoices, reports, or just trying to keep your PDF generation code sane, React-PDF remains a solid choice—and a great example of the open source spirit in action.

Brought to you by Joyfill — a natively embeddable PDF form builder for React developers building PDF experiences inside their Saas applications.

How to generate PDFs in the browser with Javascript (no server needed)

John Pagley — Thu, 10 Jul 2025 19:56:47 +0000

Whether you’re building a form submission workflow, generating customer invoices, or creating printable certificates, chances are you’ve run into the need to produce a polished PDF. Traditionally, this meant sending data to a server, rendering the document there, and then downloading the final file to the client.

But what if you could do it all in the browser?

Thanks to a growing ecosystem of open-source JavaScript libraries, you can now generate full-featured PDFs entirely on the client side—no server-side rendering, no infrastructure setup, and no data ever leaving the user’s machine. That’s a big win for privacy, performance, and flexibility.

In this article, we’ll walk through how browser-based PDF generation works, compare the most popular open-source libraries, and share practical examples to help you get started. We’ll also explore where these tools shine—and where they start to fall short—so you can build the right solution from the start.

Why Client-Side PDF Generation Matters

Generating PDFs directly in the browser isn’t just a neat trick—it can be a game changer for web applications.

Traditionally, developers relied on server-side libraries written in Python, PHP, Java, or Node.js to generate PDFs. While powerful, these server-based workflows come with downsides: added infrastructure, latency, data privacy concerns, and more moving parts to manage.

Modern JavaScript libraries flip this model by letting the browser do the work. That shift unlocks several key benefits:

No Server Required: You don’t need to maintain a backend or cloud service just to generate PDFs. Everything happens on the client.
Improved Privacy: Sensitive data—like personal information, form submissions, or invoices—never leaves the user’s device.
Faster Feedback Loops: Users get their PDF instantly, without the delay of uploading, processing, and downloading from a remote server.
Scalability by Default: Instead of pushing all PDF generation work to your backend, you offload the processing to each user’s browser.
Offline Capabilities: PDF generation can work without an internet connection—ideal for PWAs, field apps, and edge workflows.

For frontend developers, this means less dependency on backend infrastructure and more control over the user experience.

Exploring Your Toolkit: Open Source JavaScript Libraries

If you want to generate PDFs in the browser, you're in luck—there’s a mature ecosystem of open-source libraries that require no backend, plugins, or server setup. Each library has a distinct approach, and choosing the right one depends on your use case.

Let’s break down the three most widely used client-side PDF libraries—each with its own sweet spot:

1. jsPDF — The Lightweight Drawing API

One of the oldest and most widely adopted libraries, jsPDF gives you low-level control over PDF output. You position text and shapes using X/Y coordinates—much like drawing on a canvas.

Best for: Simple documents where you need direct, pixel-level control

Example Use Case: Generating a custom receipt or certificate with fixed formatting

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>jsPDF Receipt Example</title>
</head>
<body>
  <h1>jsPDF Example</h1>
  <button onclick="generateReceipt()">Generate Receipt PDF</button>

  <!-- Load jsPDF from CDN -->
  <script src="<https://unpkg.com/jspdf@2.5.1/dist/jspdf.umd.min.js>"></script>
  <script>
    const { jsPDF } = window.jspdf;

    function generateReceipt() {
      const doc = new jsPDF();

      doc.setFontSize(18);
      doc.text("Sales Receipt", 10, 20);

      doc.setFontSize(12);
      doc.text("Date: 2025-06-14", 10, 30);
      doc.text("Customer: John Doe", 10, 40);
      doc.text("Item: Widget X", 10, 50);
      doc.text("Total: $42.00", 10, 60);

      doc.line(10, 65, 100, 65);
      doc.text("Thank you for your purchase!", 10, 75);

      doc.save("receipt.pdf");
    }
  </script>
</body>
</html>

This imperative approach gives you full control—but you’re responsible for layout.

2. pdf-lib — Modern, Powerful, and Modular

pdf-lib is a TypeScript-first library designed for flexibility and composability. It lets you create new PDFs or modify existing ones—embedding fonts, images, and even merging files.

Best for: Advanced workflows involving form-filling, PDF editing, or programmatic composition
Example Use Case: Injecting an image (e.g., company logo) and drawing styled text on a generated page

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>pdf-lib Example</title>
</head>
<body>
  <h2>pdf-lib Demo</h2>
  <button id="generateBtn">Generate PDF</button>

  <script type="module">
    import { PDFDocument, rgb, StandardFonts } from '<https://cdn.skypack.dev/pdf-lib>';

    document.getElementById('generateBtn').addEventListener('click', async () => {
      const pdfDoc = await PDFDocument.create();
      const page = pdfDoc.addPage([600, 400]);

      const font = await pdfDoc.embedFont(StandardFonts.HelveticaBold);
      page.setFont(font);
      page.setFontSize(24);
      page.drawText("Welcome to MyApp!", {
        x: 50,
        y: 350,
        color: rgb(0.2, 0.4, 0.8)
      });

      // Safe CORS-compliant image
      const imageUrl = '<https://upload.wikimedia.org/wikipedia/commons/thumb/a/a3/June_odd-eyed-cat.jpg/320px-June_odd-eyed-cat.jpg>';
      const imgBytes = await fetch(imageUrl).then(res => res.arrayBuffer());
      const jpgImage = await pdfDoc.embedJpg(imgBytes);
      page.drawImage(jpgImage, {
        x: 50,
        y: 150,
        width: 100,
        height: 100
      });

      const pdfBytes = await pdfDoc.save();
      const blob = new Blob([pdfBytes], { type: 'application/pdf' });
      const url = URL.createObjectURL(blob);
      const a = document.createElement('a');
      a.href = url;
      a.download = 'branded-pdflib-doc.pdf';
      a.click();
      URL.revokeObjectURL(url);
    });
  </script>
</body>
</html>

Its async nature supports advanced features while keeping things performant.

3. pdfmake — Declarative Layouts for Complex Docs

Instead of specifying coordinates, pdfmake uses a JSON-based structure to define document content. You describe paragraphs, tables, lists, and layouts in a declarative style—and it handles the rendering.

Best for: Structured documents like reports, resumes, and invoices
Example Use Case: Generating a table-based invoice with customer info, itemized rows, and total

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>pdfmake Invoice Example</title>
</head>
<body>
  <h1>pdfmake Example</h1>
  <button onclick="generateInvoice()">Generate Invoice PDF</button>

  <!-- Load pdfmake and default font support -->
  <script src="<https://cdnjs.cloudflare.com/ajax/libs/pdfmake/0.2.7/pdfmake.min.js>"></script>
  <script src="<https://cdnjs.cloudflare.com/ajax/libs/pdfmake/0.2.7/vfs_fonts.js>"></script>

  <script>
    function generateInvoice() {
      const docDefinition = {
        content: [
          { text: "Invoice", style: "header" },
          { text: "Customer: Jane Smith", margin: [0, 10, 0, 10] },
          {
            table: {
              headerRows: 1,
              widths: ["*", "auto", "auto"],
              body: [
                ["Item", "Qty", "Price"],
                ["Widget A", "2", "$10.00"],
                ["Widget B", "1", "$22.00"],
                [{ text: "Total", bold: true }, "", "$42.00"]
              ]
            }
          },
          { text: "Thank you for your business!", margin: [0, 20, 0, 0] }
        ],
        styles: {
          header: { fontSize: 18, bold: true }
        }
      };

      pdfMake.createPdf(docDefinition).download("invoice.pdf");
    }
  </script>
</body>
</html>

This approach is especially helpful when content is template-driven or user-generated.

Each library has trade-offs, and many developers combine them depending on the task. But no matter which you choose, they all offer a serverless path to PDF generation entirely within the browser.

Challenges and Limitations of Client-Side PDF Generation

Generating PDFs in the browser is powerful—but not without trade-offs. Even the best tools can stumble when pushed beyond their ideal use cases. Here are the most common challenges developers face when working with client-side libraries:

Layout Control vs. Abstraction

Low-level libraries like jsPDF offer precise positioning, but require you to manually handle X/Y coordinates for every element.
High-level libraries like pdfmake manage layout for you, but may lack flexibility for advanced or pixel-perfect designs.
pdf-lib sits in the middle, giving you drawing primitives without full layout abstraction.

This means your choice of library often comes down to how much control—or convenience—you need.

Font Embedding and Rendering

While most libraries support standard fonts like Helvetica, using custom fonts adds complexity:

You may need to embed the font yourself as a binary asset.
Font files increase output size.
Rendering quirks can occur if the browser or PDF viewer handles font hinting differently.

Getting consistent typography across devices means being deliberate with font choices and testing thoroughly.

Performance and File Size

PDF generation happens in the user’s browser—so:

Large images or many pages can cause noticeable lag.
Complex PDFs may freeze the UI or cause memory spikes.
Mobile devices are especially vulnerable to performance issues.

Consider lazy generation, compressing images before embedding, or splitting long documents into smaller ones.

Styling Constraints

Client-side libraries don’t support CSS like display: flex or position: relative. Instead, you use their own APIs:

jsPDF requires you to set positions manually.
pdfmake uses a JSON schema for layout and styles.
pdf-lib uses function calls to draw text, shapes, and images.

If you’re trying to replicate a full HTML layout in a PDF, expect to re-implement much of your design logic in JavaScript.

Lack of Complex HTML-to-PDF Support

Libraries like jsPDF, pdf-lib, and pdfmake don’t convert HTML+CSS into PDFs.

You can’t just pass in a DOM element and expect a pixel-perfect PDF.

If that’s your use case (e.g. printing an invoice styled with Bootstrap), you may need:

Server-side rendering (e.g. Puppeteer or wkhtmltopdf)
Commercial HTML-to-PDF tools
A redesign of the layout using drawing primitives

Async Loading and Bundle Size

Most modern PDF libraries—especially pdf-lib and pdfmake—are non-trivial in size:

pdf-lib is around 400–500 KB minified.
pdfmake is even larger due to embedded font files.
Tree-shaking may help, but full optimization isn’t always possible.

In addition, some libraries (like pdf-lib) rely on async functions to fetch fonts, images, or load existing documents. This can delay rendering or require await chains that must be handled gracefully in your app. On the flip side, this async design also enables dynamic generation based on user input or remote assets—making it highly flexible for interactive applications.

If performance and initial load times matter, consider lazy-loading the PDF module only when needed, and avoid bundling it into your main application bundle.

Browser Compatibility and CORS Caveats

Most modern browsers fully support the APIs used by these libraries—like Blob, Canvas, and TypedArray—but edge cases do exist:

Safari and Firefox may handle downloads or blob: URLs differently
Mobile browsers may struggle with memory-heavy operations
Internet Explorer is not supported by most libraries

Also, if your document includes external images or fonts, you’ll need to consider CORS (Cross-Origin Resource Sharing):

Images loaded from third-party domains must allow cross-origin access via proper headers.
If not, the browser will block them—and your PDF may generate with missing assets or crash altogether.

To avoid this:

Host your assets on a CORS-compliant CDN
Or embed images as Base64 if the size is manageable

🔒 CORS isn’t a limitation of the PDF libraries—it’s a browser security model designed to protect users from unauthorized data access.

These challenges don’t make client-side PDF generation a bad choice. But they highlight why understanding your document’s complexity, audience, and platform is key to choosing the right approach.

In the next section, we’ll zoom out and compare the three open-source libraries more directly—so you can make an informed choice based on your real-world needs.

Choosing the Right Tool for the Job

Now that you've seen how jsPDF, pdf-lib, and pdfmake work in practice, you might be wondering: which one’s right for your project?

Each library takes a fundamentally different approach to PDF generation—and those differences matter when it comes to layout control, workflow complexity, and styling behavior.

At a Glance

Library	Best For	Control Level	Layout Style	Learning Curve
jsPDF	Simple exports like receipts, labels, or tickets	High (manual drawing)	Absolute (XY-based)	Low
pdf-lib	Dynamic content, form field injection, font/image handling	High (programmatic)	Object-oriented	Moderate
pdfmake	Reports, invoices, structured layouts	Moderate	Declarative (JSON)	Moderate

Summary of Use Cases

Reach for jsPDF when you want fast, direct control over every element’s position. Perfect for receipts, name badges, or static certificates where you're “drawing” the output manually.
Use pdf-lib if you need to embed images or fonts, dynamically compose content, or manipulate existing PDFs. It’s powerful for branded docs, custom form generators, and workflows that evolve over time.
Choose pdfmake when you need structured layouts like tables, sections, and styled text blocks. It excels at generating professional-looking documents like invoices, resumes, and reports with consistent formatting.

💡 Dev Tip: Think of jsPDF like painting on a blank canvas, pdf-lib like assembling pages with precision tools, and pdfmake like filling in a smart document template.

Font Handling: Small Detail, Big Impact

One subtle but important difference among these libraries is how they handle fonts:

jsPDF uses built-in fonts like Helvetica by default, with optional embedding via TTF.
pdf-lib lets you embed custom fonts explicitly—but you must load them manually.
pdfmake includes a default virtual font set but also supports embedding your own.

Why it matters: font behavior affects file size, styling consistency, and cross-platform rendering. Always test how your chosen library handles fonts before going to production.

Pro Tip

These tools aren’t mutually exclusive. Real-world projects often combine them:

Use pdfmake for templated invoices.
Use pdf-lib to inject content into dynamic or prebuilt PDFs.
Use PDF.js to preview everything right in the browser.

Your best bet? Start with a small prototype. Pick the library that gets you 80% of the way—and experiment with others if your needs grow.

When (and Why) to Consider Higher-Level Solutions

Browser-based libraries like jsPDF, pdf-lib, and pdfmake offer tremendous flexibility. But as your frontend workflows grow more dynamic, you might hit the limits of what these tools can do on their own—especially when your app goes beyond static file generation.

Signs You've Outgrown Low-Level Libraries

If you find yourself building complex document features entirely in the browser, you may be running into patterns that signal the need for a more structured, scalable approach:

Forms with conditional logic or dynamic field visibility
User input validation (e.g., required fields, custom formats)
Mapping JSON data into complex form layouts
Managing reusable templates or versioned form designs
Previewing and filling PDFs across desktop and mobile
Coordinating multi-step flows like submissions or approvals

These needs go beyond drawing boxes and adding fonts—they require logic, layout awareness, and maintainability that most low-level libraries weren’t designed to handle alone.

The Developer Dilemma

To bridge those gaps, developers often create workarounds—some clever, some brittle:

Building parallel JSON data models to match the layout structure
Manually syncing field logic across UI and PDF
Writing helper code to simulate dynamic behavior
Re-generating entire PDFs for minor changes or validation updates

These DIY approaches may work at first, but they become increasingly fragile, especially as form complexity, mobile responsiveness, and user expectations rise.

What High-Level Solutions Offer

Modern tools like Joyfill take a different approach—rethinking PDF generation from a data-first, logic-aware perspective:

Structured data over hardcoded layout: Define forms using JSON models rather than absolute positions.
Built-in validation and logic rules: Control visibility, required fields, and user behavior directly in the form definition.
Responsive, form-aware UIs: Let your documents adapt to screen sizes, user roles, or conditional logic—all in the browser.
Standards-compliant PDFs on demand: Output polished files only when needed—while keeping your logic and data separate.

This kind of separation—between content, logic, and layout—gives developers the flexibility to scale document features without scaling technical debt.

Whether you're building a complex field form, a versioned contract workflow, or a dynamic report interface, higher-level SDKs can free you from reinventing the wheel in JavaScript.

Final Thoughts: Build Smart, Ship Faster

Client-side PDF generation is no longer a niche capability—it’s a practical tool every modern web developer should know. With libraries like jsPDF, pdf-lib, and pdfmake, you can build everything from invoices to reports, certificates to receipts—all without touching a server.

You don’t need to spin up a backend just to create a PDF. You don’t need to expose sensitive data to external services. And you don’t need to wrestle with outdated desktop workflows just to get high-quality documents into the hands of your users.

But as your requirements grow—especially when working with complex forms, workflows, or large-scale PDF templates—you might find yourself needing more.

If you need to build PDF capabilities inside your SaaS application? Joyfill makes it easy for developers to natively build and embed form and PDF experiences inside their own SaaS applications.

The skeleton of a PDF: What developers should know before handling PDFs

John Pagley — Thu, 03 Jul 2025 14:43:58 +0000

Whether you’re exporting a report, building a form, or rendering a document in the browser, the PDF remains a core part of digital workflows. But while PDFs look simple on the surface, they hide a surprisingly intricate structure underneath.

Most developers only see the output—a polished, static page. But inside, a PDF is made up of nested objects, streams of compressed data, and a cross-referenced map that tells the viewer how everything fits together.

Understanding this skeleton isn’t just an academic exercise—it’s critical for anyone who plans to parse, modify, or generate PDFs using tools like pdf-lib, jsPDF, PDF rendering engines, or even a full-blown PDF SDK. Before you dive into manipulating fields or merging documents, here’s what you should know about how PDFs actually work.

The Core Structure of a PDF

At its core, a PDF is a file format that prioritizes visual fidelity over semantic clarity. It was designed to ensure documents render the same everywhere, regardless of OS, device, or software. But that consistency comes at the cost of complexity.

Here’s a breakdown of the key components:

1. The Header

Every PDF starts with a version identifier at the top, such as:

%PDF-1.7

This tells PDF readers which version of the spec the file follows. While it seems trivial, this header impacts how features like transparency, digital signatures, and form types are interpreted.

2. The Body (Objects, Streams, and More)

The main content of a PDF lives in its body, made up of a series of numbered indirect objects. These include:

Pages (each defined as an object)
Fonts and appearance settings
Text streams (where actual content is stored)
Image data, often compressed and embedded
Annotations (comments, highlights, form fields)

PDF objects are linked together through dictionaries and references, like a giant object graph. You don’t just read “Page 1”—you follow a chain of references to locate and decode it.

To make things more efficient, many of these objects use streams—binary chunks of compressed data that reflect PDF’s nature as a non-semantic, binary document format, often requiring additional decoding.

3. Cross-Reference Table (xref)

This is the index of the entire file. It maps each indirect object’s number (like 23 0 obj) to its exact byte offset in the file, allowing a PDF reader to jump directly to any object without scanning the entire document.

This is one of the reasons PDFs can load quickly—even large ones. But it also means that if you’re modifying a PDF manually, a tiny mistake in the xref table can render the entire file unreadable.

4. Trailer Dictionary

The trailer is the final piece of the puzzle. It tells the PDF reader:

Where the root document object is
How many objects exist
Where to start parsing the file
(Sometimes) encrypted metadata

When a PDF is opened, the reader jumps straight to the trailer to begin reconstruction of the document tree.

This structure gives PDFs their power—but also their reputation for being opaque and hard to work with. In the next section, we’ll look at why this skeleton causes headaches for developers trying to do anything beyond basic PDF exports.

Why Working with PDFs Can Be Frustrating

On paper, PDFs are ideal: consistent, portable, and visually locked-in. But under the hood, developers often discover that working with them is anything but straightforward.

Here’s why PDF handling tends to become frustrating—especially when you’re trying to do more than just generate a static file.

Rendering vs. Meaning

A PDF preserves how something looks, not necessarily what it means. That’s by design. PDFs were never intended to carry semantic structure like HTML or JSON.

A heading might just be bold text—not tagged as a heading.
A table is just lines and text—not a data grid.
A form field might be called /Tx1, offering no hint as to what it represents.

This lack of context makes it incredibly hard to extract meaningful data. Parsing PDFs often feels like reverse engineering a printed page.

Binary and Stream Complexity

PDFs aren't plain text documents. Content is stored in compressed binary streams, often requiring special decoding just to view or edit. That means:

You can’t reliably “grep” a PDF for a string.
Even libraries like pdf-lib or pdf-parse need to decompress and reconstruct object graphs to work with form fields or content streams.
Minor corruption in a stream or xref table can break the whole file.

For devs used to parsing JSON or rendering HTML, this binary architecture feels alien and slow to work with.

Precision and Layout Pitfalls

Unlike web layouts that adapt to screen size, PDFs use fixed positioning—every element has X/Y coordinates.

That sounds simple, but it gets tricky fast:

Adding content requires recalculating positions and avoiding overlaps.
Page breaks don’t happen automatically.
Fonts, line heights, and encoding quirks can result in layout bugs that are hard to debug.

This makes dynamic content—like forms with variable sections—very difficult to generate or maintain.

No Built-In Semantics for Workflows

PDFs don’t have built-in concepts for:

Conditional fields
Field validation logic
Data binding or API integration
Workflow routing or status tracking

Anything beyond basic fill-and-save requires custom scripting or building middleware around the file—adding complexity and fragility.

Pitfalls Developers Often Encounter

Even experienced developers hit snags when working with PDFs in real-world apps. These aren’t theoretical issues—they come from building production systems with PDFs at the core.

Here are some of the most common pitfalls:

Mistaking Viewers for Editors

Libraries like PDF.js render PDFs beautifully—but they don’t let you modify them. Developers often assume they can use such libraries for editing, only to realize they need a separate tool for creation or manipulation.

Assuming Form Support Means Interactivity

Most open-source PDF tools support static AcroForms—but not dynamic logic, conditional fields, or real-time validation. You can add a text field, sure—but try hiding it based on a user response, and you’re stuck.

Combining Multiple Libraries and Hoping It Works

A common workaround: use pdf-lib to modify files, PDF.js to render previews, and pdf-fill-form to inject data. It works—until it doesn’t. Each library may interpret PDFs slightly differently, resulting in inconsistent behavior across platforms.

Building Custom Logic Around Static Files

Need to validate a required field? Route a form submission? Bind it to a live API?

None of that is natively supported. Developers often write brittle scripts or stand up backend jobs just to make PDFs “smart.” It’s like rebuilding logic that should live in a UI or data layer—but stuffing it inside a rigid page format.

In the next section, we’ll explore how modern tools are shifting this mindset—letting you work above the skeleton of a PDF instead of being trapped inside it.

Tools That Help You Work Above the Skeleton

Many developers eventually reach the same conclusion: working directly inside the PDF structure is too brittle and too low-level for most modern use cases. That’s where higher-level tools and abstraction layers come in.

Rather than manipulating objects, byte offsets, or raw streams, these tools let you interact with PDFs the way you’d expect in a modern environment—using declarative syntax, APIs, or structured formats.

Open Source Tools and Where They Help

pdf-lib is great for creating or modifying PDFs in both the browser and Node.js. It abstracts many low-level details, letting you merge, split, or inject content without touching byte offsets.
jsPDF is ideal for quick client-side PDF generation, like invoices or receipts, using an imperative drawing API.
pdfmake offers a JSON-based approach to defining PDF content, useful for templating and auto-generated documents.
PDF.js renders PDFs in the browser using HTML5 and JavaScript, perfect for previews and readers—but not editing.

While these tools dramatically improve the developer experience, they still stop short of enabling fully dynamic workflows or interactive form logic. They help you create and modify PDFs—but they don’t turn a PDF into an application.

The Rise of Higher-Level Layers

To overcome the limitations of PDFs themselves, some tools now take a different approach: treat the PDF as a visual output, not the center of the experience.

This means:

Define form logic in JSON, not inside a static PDF file.
Use HTML/CSS/JS to build responsive forms for mobile and web.
Generate the PDF after the data has been captured and validated—ensuring it reflects the final state of the workflow.

This “data first, PDF later” mindset is what enables faster development, better integrations, and more flexible document workflows. And that’s where Joyfill comes in.

Joyfill’s Perspective: A Higher-Level Layer

Joyfill doesn’t replace the PDF—it elevates it.

Rather than embedding brittle logic inside static files, Joyfill introduces a programmable document layer that works above the PDF format. This layer—defined in JSON via the JoyDoc schema—lets developers define field logic, conditional visibility, validations, and layout all through code.

Here’s what it offers:

A JSON-based structure (JoyDoc) for defining forms, fields, and logic
A web-powered rendering engine that works across devices and screen sizes
Built-in field validation, dynamic logic, and mobile responsiveness
A high-fidelity output engine that generates standards-compliant PDFs on demand

With Joyfill, you design your form as a modern UI—then generate the PDF after the user interaction is complete. This removes the need for scripting inside the PDF or gluing together multiple libraries.

For developers, this means:

No more fighting with streams, coordinates, or xref tables
No more maintaining fragile workflows or building custom validators
A clearer, faster, and more scalable way to work with forms, data, and PDFs

Final Thoughts

Understanding the inner workings of a PDF—the skeleton beneath the surface—can be incredibly valuable. It gives you insight into why certain limitations exist, why some bugs are hard to fix, and why tools behave the way they do.

Whether you're just starting with PDFs or looking to modernize a legacy workflow, the best path forward is the one that gives you power, clarity, and control. And that begins with knowing what's under the hood—then choosing to work smarter from there.

Building a custom PDF viewer in React with your own controls

John Pagley — Thu, 26 Jun 2025 13:44:25 +0000

Most dev teams rely on 3rd-party libraries when implementing PDF viewers in React applications. While this is a great strategy for teams that need to ship features fast, building a truly lightweight and custom PDF viewer with features like responsive viewports and toolbars for zooming and pagination might require a more hands-on approach.

Faced with the bloat of large PDF libraries, their limited customization options, and user interfaces that may clash with the look and feel of your application, the temptation to build your own PDF viewer from scratch is understandable. A DIY PDF viewer will give you complete control over its customization but it also requires a significant time investment that might be better spent on other development tasks.

Fortunately, you don’t have to choose between a restrictive library and rolling your own PDF viewer from scratch. You’re better off using a JavaScript library such as react-pdf, which offers the best of both worlds by providing a highly customizable PDF viewer for any React application.

This post shows React developers how to create a fully custom React PDF viewer with custom controls such as:

viewing remote and locally saved PDFs
a customized UI
zoom in/out
pagination

Create a new React App

As a first step, create a new React application by opening a terminal and running the following command. It should create a react-pdf-viewer folder that contains scaffolding for developing a React application.

npm create vite@latest -- --template react react-pdf-viewer

Next, navigate to the react-pdf-viewer folder and open it in your code editor or IDE.

Install dependencies

In the root directory of the react-pdf-viewer project, run the following terminal command to install react-pdf and material icons. Material icons will serve as intuitive labels for custom controls such as zoom and pagination buttons in the PDF viewer’s toolbar.

npm install react-pdf @fontsource-variable/material-symbols-outlined

Define the Application’s State

Users need to be able to navigate to other pages, zoom, see what page they’re on, and so forth when viewing a PDF document. Let’s define the initial state and how to manage changes to documents opened in the viewer by creating an src/state.js file with the following as its contents:

// src/state.js
export const initialState = {
  pdf: null, // PDF file as a { url: http/https URL to PDF file } or { data: UInt8Array of PDF file }
  numPages: null, // Total number of pages in PDF document
  pageNumber: 1, // Displays page 1 by default
  scale: 1.0, // Sets each page's dimensions to the document's page size by default
};

export function reducer(state, action) {
  switch (action.type) {
    case 'pdf':
      return { ...state, pdf: action.pdf };

    case 'num-pages':
      return { ...state, numPages: action.numPages };

    case 'arrow_left':
      if (state.pageNumber === 1) {
        return state;
      }
      return { ...state, pageNumber: state.pageNumber - 1 };

    case 'arrow_right':
      if (state.pageNumber === state.numPages) {
        return state;
      }
      return { ...state, pageNumber: state.pageNumber + 1 };

    case 'zoom_out':
      if (state.scale > 0.6) {
        return { ...state, scale: state.scale - 0.1 };
      }
      return state;

    case 'zoom_in':
      if (state.scale < 2.9) {
        return { ...state, scale: state.scale + 0.1 };
      }
      return state;

    default:
      return state;
  }
}

Create a PDFViewer Component

Create a PDFViewer.jsx file in the src folder of the project and copy the following code into it.

// src/PDFViewer.jsx
import { Document, Page, pdfjs } from 'react-pdf';

// Required CSS for react-pdf's text and annotation layers
import 'react-pdf/dist/Page/TextLayer.css';
import 'react-pdf/dist/Page/AnnotationLayer.css';

// Configure PDF worker
pdfjs.GlobalWorkerOptions.workerSrc = new URL(
  'pdfjs-dist/build/pdf.worker.min.mjs',
  import.meta.url
).toString();

function PDFViewer({ file, pageNumber, scale, dispatch }) {
  // Update the app's state to reflect the:
  // - current page number
  // - total number of pages
  function handlePageCount({ numPages }) {
    dispatch({ type: 'num-pages', numPages });
  }

  return (
    <Document file={file} onLoadSuccess={handlePageCount}>
      <Page pageNumber={pageNumber} scale={scale} />
    </Document>
  );
}

export default PDFViewer;

Add Custom Controls to the PDF Viewer

Although the above PDFViewer component is ready for use, it is currently missing the bells and whistles of most production-ready PDF viewers. Let's rectify that by creating a custom Toolbar and a ControlButton component to render the PDF viewer’s controls.

Create a Toolbar.jsx file in the src folder of the project and add the following components to it.

// src/Toolbar.jsx
import '@fontsource-variable/material-symbols-outlined';

function ControlButton({ label }) {
  return (
    <button
      className="toolbar-control material-symbols-outlined"
      type="button"
      data-action={label}
    >
      {label}
    </button>
  );
}

function Toolbar({ dispatch, pageNumber, numPages }) {
  const controls = ['arrow_right', 'zoom_in', 'zoom_out'];

  function dispatchControl(e) {
    const target = e.target;

    if (!e.target.className === 'toolbar-control') {
      return;
    }

    dispatch({ type: target.dataset.action });
  }

  return (
    <div className="toolbar" onClick={dispatchControl}>
      <ControlButton label="arrow_left" />
      <span class="page-number">{pageNumber}</span>/
      <span class="page-count">{numPages}</span>
      {controls.map((label, i) => (
        <ControlButton label={label} key={i} />
      ))}
    </div>
  );
}

export default Toolbar;

Passing a PDF File to the PDF Viewer

A PDF file is passed to react-pdf's Document component in one of two ways. It takes an object with a:

url field set to the target PDF file’s URL.
data field set to a Uint8Array .

Render a PDF from a URL

This method is ideal for situations where you need to render a PDF document located on the server or a remote file hosting service such as an S3 bucket.

For example, to show users a PDF document when they click a button, replace the contents of the src/App.jsx file with the following:

// src/App.jsx
import './App.css';
import { useReducer } from 'react';
import { reducer, initialState } from './state';
import PDFViewer from './PDFViewer';
import Toolbar from './Toolbar';

function App() {
  const [state, dispatch] = useReducer(reducer, initialState);

  function viewPdfFromUrl(e) {
    const target = e.target;

    if (!e.target.className === 'view-pdf-from-url') {
      return;
    }

    dispatch({
      type: 'pdf',
      pdf: { url: target.dataset.pdf },
    });
  }

  return (
    <>
      {state.pdf ? (
        <>
          <Toolbar
            dispatch={dispatch}
            pageNumber={state.pageNumber}
            numPages={state.numPages}
          />
          <PDFViewer
            file={state.pdf}
            pageNumber={state.pageNumber}
            scale={state.scale}
            dispatch={dispatch}
          />
        </>
      ) : (
        <button
          className="view-pdf-from-url"
          onClick={viewPdfFromUrl}
          data-pdf="<http://localhost:3001/dummy.pdf>"
        >
          View PDF
        </button>
      )}
    </>
  );
}

export default App;

Open a terminal at the root of the react-pdf-viewer folder and run npm run dev. Then visit the URL displayed in the terminal.

You should be able to click the View PDF button to view and navigate the contents of the http://localhost:3001/dummy.pdf file assuming you already have an HTTP server running on port 3001 of your computer that serves a dummy.pdf file.

The toolbar and dummy PDF file should (for now) appear similar to the following:

Render PDFs from the User's Computer

To allow users to view PDF documents stored locally on their devices, you can use a form with a file input element. To see this in action, create an src/PdfForm.jsx file and copy the following code into it:

// src/PdfForm.jsx
function PdfForm({ dispatch }) {
  async function getPdfByteArray(e) {
    // Get the File object of the uploaded PDF.
    const file = e.target.files[0];

    // Continue only if the user has uploaded a PDF document
    if (file.type !== 'application/pdf') {
      alert(`Error: ${file.name} is not a PDF file`);
      return;
    }

    // Read the contents of the PDF file from the user's device
    const reader = new FileReader();
    reader.readAsArrayBuffer(file);

    // Handle error(s) encountered while reading the contents of the PDF file
    reader.onerror = () => {
      alert(`Unable to read ${file.name} to an ArrayBuffer`);
      console.error(reader.error);
    };

    // Wait till FileReader has read all contents
    // of the PDF file before proceeding
    reader.onload = async () => {
      // Transform the contents of the PDF file to a generic byte array
      const pdfByteArray = new Uint8Array(reader.result);

      // Set the Viewer component's file prop
      dispatch({ type: 'pdf', pdf: { data: pdfByteArray } });
    };
  }

  return (
    <form className="pdf-form">
      <label htmlFor="pdf-form__input" className="pdf-form__label">
        View a PDF file saved on your computer
      </label>
      <input
        onChange={async (e) => await getPdfByteArray(e)}
        type="file"
        name="pdf-file"
        id=""
        className="pdf-form__input"
      />
    </form>
  );
}

export default PdfForm;

If we replace the contents of the src/App.jsx file with the following, we should be able open and view locally saved PDF documents.

// src/App.jsx
import './App.css';
import { useReducer } from 'react';
import { reducer, initialState } from './state';
import PDFViewer from './PDFViewer';
import Toolbar from './Toolbar';
import PdfForm from './PdfForm';

function App() {
  const [state, dispatch] = useReducer(reducer, initialState);

  return (
    <>
      {state.pdf && (
        <>
          <Toolbar
            dispatch={dispatch}
            pageNumber={state.pageNumber}
            numPages={state.numPages}
          />
          <PDFViewer
            file={state.pdf}
            pageNumber={state.pageNumber}
            dispatch={dispatch}
            scale={state.scale}
          />
        </>
      )}
      {!state.pdf && <PdfForm dispatch={dispatch} />}
    </>
  );
}

export default App;

Now that the PDF viewer works, you can apply your application’s theme to the page to stay on brand. However, since this post focuses on demonstrating how to customize the PDF viewer’s interface, the following steps should suffice:

Delete or comment out the line containing import './index.css' in the src/main.jsx file.

Replace the contents of the src/App.css file with the following:

body,
body *::before,
body *::after {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

body,
input,
input::placeholder,
button,
.pdf-form__input::file-selector-button {
  font-family: sans-serif;
  color: #1C2025;
}

body {
  background-color: rgb(239, 246, 253);
  min-height: 100vh;
  padding: 0 1em 1em;
  max-width: 100%;
}

form {
  background-color: white;
  border-radius: 1em;
  padding: 4em 2em;
  max-width: 400px;
  margin: 25vh auto;
}

label {
  font-size: 1.5rem;
  display: block;
  margin-bottom: 12px;
}

.pdf-form__input {
  display: block;
}

.pdf-form__input::file-selector-button {
  border: 2px solid rgba(0, 0, 0, 0.1);
  border-radius: 0.5em;
  padding: 0.75em;
  font-size: 1rem;
  background-color: dodgerblue;
  color: rgb(247, 247, 247);
  cursor: pointer;
}

.toolbar {
  position: absolute;
  top: 0;
  right: 0;
  left: 0;
  display: flex;
  justify-content: center;
  align-items: center;
  font-size: 1.5rem;
  gap: 0.75em;
  padding: 0.5em;
}

.toolbar-control {
  cursor: pointer;
  font-family: 'Material Symbols Outlined Variable';
  font-size: 1.75rem;
  display: inline-block;
  line-height: 1;
  text-transform: none;
  letter-spacing: normal;
  word-wrap: normal;
  white-space: nowrap;
  direction: ltr;
  border: 1px solid #bbbbbb;
}

.react-pdf__Document {
  margin: 3.2em auto 0;
  max-width: fit-content;
}

Now, reload the page. The viewer and toolbar should look similar to the following when you open a PDF file.

Using the react-pdf library to build a custom PDF viewer provides a solid foundation for creating a lightweight, tailored document viewing experience. This is largely because the library abstracts the complexity of rendering PDFs while still allowing developers to customize the document’s interface and controls.

This post has demonstrated how to render both remote and locally stored PDFs, as well as how to implement essential custom controls such as zoom in/out functionality and pagination. However, the possibilities for customization extend far beyond these basics when leveraging a lightweight and flexible library like react-pdf.

If this was just the beginning of your PDF build and you want to achieve more robust capabilities, check out Joyfill — a PDF form filler SDK that you can embed into your web or mobile app.