Building PDF reports with jsPDF: when you need a report designer instead

Where jsPDF is excellent

It is worth being clear about this first, because most of the advice on the internet about “outgrowing jsPDF” is written by people selling something and starts from the premise that you should never have used it. That premise is wrong.

jsPDF is the right tool when:

• the document is short and its shape does not depend much on the data;
• you want a small MIT-licensed dependency in the browser, with nothing running on a server;
• you are drawing at coordinates — a receipt, a label, a certificate, a ticket — rather than laying out prose;
• a developer is content to be the person who places things, because things rarely move.

Under those conditions it is hard to beat. Four lines and you have a PDF, in a browser, with no build configuration and no service.

import { jsPDF } from "jspdf";

const doc = new jsPDF();
doc.setFontSize(18);
doc.text("Invoice 10241", 20, 24);
doc.setFontSize(11);
doc.text("Aldermead Joinery Ltd", 20, 34);
doc.save("invoice.pdf");

The seven-step progression

This is the same sequence in almost every codebase that ends up here. It is worth recognising which step you are on, because the cost of changing course goes up sharply at step five and the decision usually gets made at step seven, when it is most expensive.

// Two hours later, the cursor exists.
let y = 24;
const MARGIN = 20;
const BOTTOM = doc.internal.pageSize.getHeight() - MARGIN;

function line(text: string, size = 11, leading = 6) {
  doc.setFontSize(size);
  // Wrapping is yours to ask for, and the answer is an array of lines.
  for (const part of doc.splitTextToSize(text, 170)) {
    if (y + leading > BOTTOM) {
      doc.addPage();
      y = MARGIN;
    }
    doc.text(part, MARGIN, y);
    y += leading;
  }
}

// What you actually wanted to write, and cannot.
//
// The height of the chart is known — you chose it. The height of the
// heading is roughly known. The height of the paragraph underneath is
// not, because it depends on wrapping, which depends on the font, which
// depends on whether the customer's brand loaded.
//
// So this function has to measure something that has not been drawn:
function keepTogether(blocks: Block[]) {
  const height = blocks.reduce((total, b) => total + measure(b), 0);
  //                                                  ^^^^^^^
  //                                        this is the library you are writing
  if (y + height > BOTTOM) { doc.addPage(); y = MARGIN; }
  for (const b of blocks) draw(b);
}

// Branding, once there is more than one customer.
doc.addFileToVFS("Aldermead-Regular.ttf", base64Font);
doc.addFont("Aldermead-Regular.ttf", "Aldermead", "normal");
doc.setFont("Aldermead");

// And now every measurement above is wrong, because they were all
// taken against Helvetica.

Where the line actually is

It is further along than most people assume, and it is not about document count or complexity. It is about who needs to be able to change the layout, and how often.

Stay with jsPDF if all of these are true:

• Engineering owns every document, and is happy to.
• Layout changes arrive at roughly the rate of releases, not faster.
• The documents are short enough that pagination is a page-full check rather than a set of rules.
• Nobody has ever asked for a document to look different for a particular customer.

Start looking when any two of these are true:

• You have written a measure() function, or you are about to.
• There is a folder of templates and the difference between two of them is not obvious from the filenames.
• “Report changes” is a recurring item in planning.
• A sales conversation has turned on whether a layout can be changed.
• Somebody has asked for the header on a second page, and you had to think about it.

What the alternatives cost

There are three honest directions, and they fail differently.

Facts about jsPDF here come from its own documentation and repository, and from jspdf-autotable and svg2pdf.js, checked on the date at the top of this page: jsPDF, its API docs, jspdf-autotable, svg2pdf.js. If something has changed, tell us at hello@broadpaper.com.

Where BroadPaper fits

BroadPaper is the third direction. It is an embeddable visual report designer: you declare the data fields that exist, your users lay the document out against them, and the SDK owns measurement, pagination, branding and the PDF. What gets saved is JSON, so a layout becomes a row in your database rather than a file in your repository.

The three things from the progression above that it takes off you completely:

• Measurement and pagination. Sections are measured as one continuous galley and a pure paginator assigns each page a clip window, so keep-together, orphans and widows, repeated table headers and “page 3 of 7” are settings rather than code. Neither the browser nor the PDF engine gets a vote.
• Branding. A template that names theme tokens re-brands with one option. Fonts are declared once and the same TrueType bytes both measure the layout and draw the file, so changing the typeface does not silently invalidate every height in the document.
• The last step. Customers changing layouts is the thing the product is for, rather than the thing it cannot do.

There is no migration path, and that is not a dodge — jsPDF code is a sequence of drawing calls and a BroadPaper report is data, so nothing converts between them. Teams who move usually leave the fixed receipt exactly where it is and reach for the designer for the document that outgrew being placed by hand.

If you want the two side by side rather than the story: jsPDF and BroadPaper, feature by feature.