DEV Community: Fred T

Generate PDF Certificates for Your Online Course

Fred T — Fri, 20 Mar 2026 17:00:00 +0000

Introduction

Completion certificates are one of the most tangible rewards you can offer students who finish your online course. They validate effort, look good on a LinkedIn profile, and give your platform a professional edge. The problem is that creating them manually does not scale. Once you have a few hundred graduates per cohort, opening a design tool and swapping out names is no longer an option.

In this tutorial, you will build a certificate generation pipeline with DocuForge that handles everything end to end. You will design a polished certificate template with Handlebars placeholders, embed a QR code that links to a verification page, generate a single certificate to test the flow, and then batch-generate certificates for an entire cohort in one API call. You will also add draft watermarks for preview mode and wire up email delivery so each student receives their certificate automatically.

By the end, you will have a production-ready system that turns a list of student records into individually personalized, verifiable PDF certificates with no manual intervention.

Step 1: Design the Certificate Template

A certificate needs to look the part. Gold accents, elegant typography, and a formal layout go a long way toward making recipients feel that their achievement matters. The template below uses a decorative double border, serif headings, and a centered composition that works well in landscape orientation.

<!DOCTYPE html>
<html>
<head>
  <style>
    @import url('https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;700&family=Lato:wght@300;400&display=swap');

    * {
      margin: 0;
      padding: 0;
      box-sizing: border-box;
    }

    body {
      width: 297mm;
      height: 210mm;
      font-family: 'Lato', sans-serif;
      background: #fffdf7;
      display: flex;
      align-items: center;
      justify-content: center;
    }

    .certificate {
      width: 267mm;
      height: 180mm;
      border: 3px solid #b8860b;
      outline: 1px solid #d4a84b;
      outline-offset: 6px;
      padding: 32px 48px;
      display: flex;
      flex-direction: column;
      align-items: center;
      justify-content: space-between;
      position: relative;
    }

    .certificate::before,
    .certificate::after {
      content: '';
      position: absolute;
      width: 40px;
      height: 40px;
      border: 2px solid #b8860b;
    }

    .certificate::before {
      top: 8px;
      left: 8px;
      border-right: none;
      border-bottom: none;
    }

    .certificate::after {
      bottom: 8px;
      right: 8px;
      border-left: none;
      border-top: none;
    }

    .header {
      text-align: center;
    }

    .header .org-name {
      font-family: 'Lato', sans-serif;
      font-weight: 300;
      font-size: 14px;
      letter-spacing: 4px;
      text-transform: uppercase;
      color: #888;
      margin-bottom: 8px;
    }

    .header .title {
      font-family: 'Playfair Display', serif;
      font-size: 42px;
      font-weight: 700;
      color: #1a1a1a;
      letter-spacing: 2px;
    }

    .divider {
      width: 120px;
      height: 2px;
      background: linear-gradient(90deg, transparent, #b8860b, transparent);
      margin: 4px 0;
    }

    .body {
      text-align: center;
    }

    .body .preamble {
      font-size: 14px;
      color: #666;
      letter-spacing: 2px;
      text-transform: uppercase;
      margin-bottom: 12px;
    }

    .body .student-name {
      font-family: 'Playfair Display', serif;
      font-size: 36px;
      font-weight: 700;
      color: #b8860b;
      margin-bottom: 16px;
    }

    .body .description {
      font-size: 15px;
      color: #444;
      line-height: 1.6;
      max-width: 500px;
    }

    .body .course-title {
      font-weight: 400;
      color: #1a1a1a;
    }

    .footer {
      display: flex;
      align-items: flex-end;
      justify-content: space-between;
      width: 100%;
    }

    .footer .detail {
      text-align: center;
    }

    .footer .detail .label {
      font-size: 10px;
      color: #999;
      text-transform: uppercase;
      letter-spacing: 2px;
      margin-bottom: 4px;
    }

    .footer .detail .value {
      font-size: 13px;
      color: #333;
    }

    .footer .qr {
      text-align: center;
    }

    .footer .qr .qr-label {
      font-size: 9px;
      color: #aaa;
      text-transform: uppercase;
      letter-spacing: 1px;
      margin-top: 4px;
    }
  </style>
</head>
<body>
  <div class="certificate">
    <div class="header">
      <div class="org-name">Your Academy</div>
      <div class="title">Certificate of Completion</div>
    </div>

    <div class="divider"></div>

    <div class="body">
      <div class="preamble">This is proudly presented to</div>
      <div class="student-name">{{student_name}}</div>
      <div class="description">
        for successfully completing the course
        <span class="course-title">{{course_title}}</span>
        on {{completion_date}}.
      </div>
    </div>

    <div class="footer">
      <div class="detail">
        <div class="label">Date</div>
        <div class="value">{{completion_date}}</div>
      </div>
      <div class="qr">
        {{qr:https://yoursite.com/verify/{{certificate_id}}}}
        <div class="qr-label">Scan to verify</div>
      </div>
      <div class="detail">
        <div class="label">Certificate ID</div>
        <div class="value">{{certificate_id}}</div>
      </div>
    </div>
  </div>
</body>
</html>

The {{qr:...}} placeholder is a DocuForge feature that replaces the tag with an inline SVG QR code at render time. No external library is needed. The QR encodes a URL pointing to your verification endpoint, which you will build in Step 3.

Now store this template in DocuForge so you can reference it by ID in every generation call:

import DocuForge from "docuforge";

const df = new DocuForge("df_live_your_api_key");

const template = await df.templates.create({
  name: "Course Completion Certificate",
  html_content: certificateHtml, // the HTML string above
  schema: {
    student_name: { type: "string", required: true },
    course_title: { type: "string", required: true },
    completion_date: { type: "string", required: true },
    certificate_id: { type: "string", required: true },
  },
});

console.log(template.id); // tmpl_xxxxxxxx

The schema is optional but recommended. It documents which variables the template expects and enables validation at generation time, so a missing field returns a clear error instead of a blank spot on the certificate.

Step 2: Generate a Single Certificate

With the template stored, generating a certificate for one student is a single call to df.fromTemplate(). This is useful for testing the design and for on-demand generation when a student completes a course in real time.

const certificate = await df.fromTemplate({
  template: "tmpl_xxxxxxxx",
  data: {
    student_name: "Alice Johnson",
    course_title: "Advanced TypeScript Patterns",
    completion_date: "March 15, 2026",
    certificate_id: "CERT-2026-00412",
  },
  options: {
    format: "A4",
    orientation: "landscape",
    printBackground: true,
    margin: { top: "0mm", right: "0mm", bottom: "0mm", left: "0mm" },
  },
});

console.log(certificate);
// {
//   id: "gen_abc123",
//   status: "completed",
//   url: "https://storage.docuforge.com/pdfs/gen_abc123.pdf",
//   pages: 1,
//   file_size: 48210,
//   generation_time_ms: 320
// }

A few things to note. Setting all margins to 0mm lets the CSS handle spacing internally, which keeps the decorative border flush with the page edge. The printBackground option must be true or the cream background and gold gradient divider will not render. The response includes a hosted URL where the PDF is immediately available for download.

Open the URL in a browser and confirm that the layout, fonts, QR code, and text substitution all look correct before moving on to batch generation. It is much easier to fix a styling issue now than after you have generated 500 certificates.

Step 3: Build a Verification Endpoint

The QR code on each certificate links to a URL like https://yoursite.com/verify/CERT-2026-00412. For that link to mean anything, you need a verification endpoint that confirms the certificate is authentic and displays the relevant details.

Start by storing certificate records whenever you generate one:

// After each successful generation, persist the record
await db.insert(certificates).values({
  certificateId: "CERT-2026-00412",
  studentName: "Alice Johnson",
  courseTitle: "Advanced TypeScript Patterns",
  completionDate: "2026-03-15",
  pdfUrl: certificate.url,
  generationId: certificate.id,
  createdAt: new Date(),
});

Then expose a route that looks up the record:

app.get("/verify/:certificateId", async (req, res) => {
  const record = await db
    .select()
    .from(certificates)
    .where(eq(certificates.certificateId, req.params.certificateId))
    .limit(1);

  if (record.length === 0) {
    return res.status(404).json({ valid: false, message: "Certificate not found" });
  }

  const cert = record[0];
  return res.json({
    valid: true,
    student_name: cert.studentName,
    course_title: cert.courseTitle,
    completion_date: cert.completionDate,
    pdf_url: cert.pdfUrl,
  });
});

When someone scans the QR code on a printed certificate, they land on this endpoint (or a frontend page that calls it) and see confirmation that the certificate is legitimate, along with the student name and course title. This is a simple but effective anti-fraud measure. If you want to go further, you can render a branded verification page with your logo and a green checkmark instead of returning raw JSON.

Step 4: Batch Generate for a Cohort

Generating certificates one at a time works for individual completions, but when a cohort of 200 students finishes a course on the same day, you want a single API call. The df.batch() method accepts an array of generation items and processes them asynchronously via a job queue.

const students = [
  { name: "Alice Johnson", id: "CERT-2026-00412" },
  { name: "Bob Martinez", id: "CERT-2026-00413" },
  { name: "Clara Chen", id: "CERT-2026-00414" },
  // ... up to hundreds of students
];

const batchResult = await df.batch({
  items: students.map((student) => ({
    template: "tmpl_xxxxxxxx",
    data: {
      student_name: student.name,
      course_title: "Advanced TypeScript Patterns",
      completion_date: "March 15, 2026",
      certificate_id: student.id,
    },
    options: {
      format: "A4",
      orientation: "landscape",
      printBackground: true,
      margin: { top: "0mm", right: "0mm", bottom: "0mm", left: "0mm" },
    },
  })),
  webhook: "https://yoursite.com/webhooks/certificates-ready",
});

console.log(batchResult);
// {
//   batch_id: "batch_xyz789",
//   total: 3,
//   generations: [
//     { id: "gen_001", index: 0 },
//     { id: "gen_002", index: 1 },
//     { id: "gen_003", index: 2 }
//   ],
//   status: "queued"
// }

The response returns immediately with HTTP 202. Each item in the generations array has an id you can use to poll status with df.getGeneration(id), but the more practical approach is the webhook parameter. When every item in the batch has finished processing, DocuForge sends a POST request to your webhook URL with the full results. Your webhook handler can then persist the certificate records and trigger email delivery, which you will set up in Step 6.

The batch queue processes jobs with a concurrency of 5 and retries failed items up to 3 times with exponential backoff. For most cohort sizes, all certificates will be ready within a few minutes.

Step 5: Add a Watermark for Draft Previews

Before you finalize a new certificate design or a new course title, it helps to generate a preview that is clearly marked as non-final. DocuForge supports text watermarks as a generation option. Add one during your review cycle and remove it for the production run.

const preview = await df.fromTemplate({
  template: "tmpl_xxxxxxxx",
  data: {
    student_name: "Test Student",
    course_title: "Advanced TypeScript Patterns",
    completion_date: "March 15, 2026",
    certificate_id: "CERT-PREVIEW",
  },
  options: {
    format: "A4",
    orientation: "landscape",
    printBackground: true,
    margin: { top: "0mm", right: "0mm", bottom: "0mm", left: "0mm" },
  },
  watermark: {
    text: "PREVIEW",
    color: "#888888",
    opacity: 0.1,
    angle: -45,
    fontSize: 72,
  },
});

The watermark renders as a large diagonal text overlay across the page. An opacity of 0.1 keeps it visible enough to signal "draft" without obscuring the design underneath. Share the preview URL with your team for sign-off. Once the design is approved, remove the watermark property from your generation calls and proceed with the real batch run.

This is also useful if you offer students a preview of their certificate before they make a final payment or complete a capstone project. Show them the watermarked version as motivation, then deliver the clean version upon completion.

Step 6: Email Certificates

With the batch complete and PDF URLs in hand, the last step is delivering each certificate to its recipient. You can loop through the results and send an email with a download link, or attach the PDF directly.

The simplest approach uses the hosted URL that DocuForge provides:

import { Resend } from "resend";

const resend = new Resend("re_your_api_key");

async function emailCertificates(
  students: { name: string; email: string; generationId: string }[]
) {
  for (const student of students) {
    const generation = await df.getGeneration(student.generationId);

    await resend.emails.send({
      from: "certificates@youracademy.com",
      to: student.email,
      subject: "Your Course Completion Certificate",
      html: `
        <h2>Congratulations, ${student.name}!</h2>
        <p>
          You have successfully completed the course. Your certificate
          is ready for download.
        </p>
        <p>
          <a href="${generation.url}">Download your certificate (PDF)</a>
        </p>
        <p>
          Your certificate can be independently verified at any time using
          the QR code printed on it.
        </p>
      `,
    });
  }
}

If you prefer to attach the PDF directly to the email instead of linking to a hosted URL, generate with output: 'base64' and pass the result as an attachment:

const cert = await df.fromTemplate({
  template: "tmpl_xxxxxxxx",
  data: { /* student data */ },
  options: {
    format: "A4",
    orientation: "landscape",
    printBackground: true,
    margin: { top: "0mm", right: "0mm", bottom: "0mm", left: "0mm" },
  },
  output: "base64",
});

await resend.emails.send({
  from: "certificates@youracademy.com",
  to: "alice@example.com",
  subject: "Your Course Completion Certificate",
  html: "<p>Your certificate is attached.</p>",
  attachments: [
    {
      filename: "certificate.pdf",
      content: cert.url, // base64 string when output is 'base64'
    },
  ],
});

The attachment approach guarantees the student has the file even if the hosted URL eventually expires, but it does increase email size. For most use cases, the download link is cleaner and avoids email deliverability issues that come with large attachments.

When processing a large cohort, add a short delay between sends or use your email provider's batch API to avoid hitting rate limits.

Going Further

You now have a complete pipeline: a polished template, single and batch generation, QR verification, draft previews, and email delivery. Here are a few directions to extend it.

If your course platform handles payments, you can use the same template and generation pattern to produce Stripe-style invoices for each transaction. The Stripe invoice tutorial walks through that setup.

For more complex certificate layouts that include dynamic charts or interactive elements, consider building the certificate as a React component and rendering it with df.generate({ react: ... }). The React PDF export guide covers the approach in detail.

Finally, if you need to fine-tune page dimensions, header and footer placement, or multi-page layouts, the page layout guide is a useful reference.

Generate Report PDFs from Supabase Data

Fred T — Fri, 20 Mar 2026 13:00:00 +0000

Generate Report PDFs from Supabase Data

Your Supabase database holds everything: orders, users, revenue, product performance. But when the CEO asks for a weekly sales summary, nobody wants to stare at a JSON response. Stakeholders want polished, printable PDFs they can skim in a meeting, forward to investors, or archive for compliance.

Building a reporting pipeline from scratch means stitching together a query layer, a templating engine, a PDF renderer, and a delivery mechanism. That is a lot of surface area for bugs.

In this tutorial, you will build a complete reporting pipeline that queries sales data from Supabase, feeds it into a Handlebars template with tables and QR codes, generates a pixel-perfect PDF with DocuForge, stores the result back in Supabase, and automates the whole thing with an Edge Function. You will also see how to scale to multi-client batch reports using the DocuForge batch API.

Step 1: Set Up the Project

Start by creating a new Node.js project and installing the two dependencies you need: the DocuForge SDK for PDF generation and the Supabase client for database queries.

mkdir sales-report-generator
cd sales-report-generator
npm init -y
npm install docuforge @supabase/supabase-js

Add your credentials to a .env file. Never commit this file to version control.

DOCUFORGE_API_KEY=df_live_your_api_key_here
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1NiIs...

Use the service role key here, not the anon key. You are running this on the server and need unrestricted access to query across all rows without row-level security filtering. In a production setup, you would scope this down with a custom role, but the service key is fine for a reporting script.

Create a report.ts file and initialize both clients:

// report.ts
import DocuForge from "docuforge";
import { createClient } from "@supabase/supabase-js";

const df = new DocuForge(process.env.DOCUFORGE_API_KEY!);

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_KEY!
);

With both clients ready, you can start querying data.

Step 2: Query Data from Supabase

A useful sales report needs more than a raw list of orders. You need aggregated totals, a daily breakdown for trend analysis, and a ranked list of top-selling products. All of this can come from a single Supabase table with a few well-structured queries.

Assume your orders table has columns for id, created_at, product_name, quantity, total_price, and status. Here is how to pull the data for a given date range and transform it into a report-ready shape:

interface ReportData {
  report_title: string;
  date_range: string;
  generated_at: string;
  total_revenue: string;
  total_orders: number;
  average_order_value: string;
  daily_data: { date: string; orders: number; revenue: string }[];
  top_products: { name: string; units_sold: number; revenue: string }[];
  report_url: string;
}

async function queryReportData(
  startDate: string,
  endDate: string
): Promise<ReportData> {
  // Fetch all completed orders in the date range
  const { data: orders, error } = await supabase
    .from("orders")
    .select("*")
    .gte("created_at", startDate)
    .lte("created_at", endDate)
    .eq("status", "completed")
    .order("created_at", { ascending: true });

  if (error) throw new Error(`Supabase query failed: ${error.message}`);
  if (!orders || orders.length === 0) throw new Error("No orders found for date range");

  // Calculate totals
  const totalRevenue = orders.reduce((sum, o) => sum + o.total_price, 0);
  const totalOrders = orders.length;
  const averageOrderValue = totalRevenue / totalOrders;

  // Build daily breakdown
  const dailyMap = new Map<string, { orders: number; revenue: number }>();
  for (const order of orders) {
    const date = order.created_at.split("T")[0];
    const existing = dailyMap.get(date) || { orders: 0, revenue: 0 };
    existing.orders += 1;
    existing.revenue += order.total_price;
    dailyMap.set(date, existing);
  }
  const dailyData = Array.from(dailyMap.entries()).map(([date, stats]) => ({
    date,
    orders: stats.orders,
    revenue: stats.revenue.toFixed(2),
  }));

  // Rank top products by revenue
  const productMap = new Map<string, { units: number; revenue: number }>();
  for (const order of orders) {
    const existing = productMap.get(order.product_name) || { units: 0, revenue: 0 };
    existing.units += order.quantity;
    existing.revenue += order.total_price;
    productMap.set(order.product_name, existing);
  }
  const topProducts = Array.from(productMap.entries())
    .map(([name, stats]) => ({
      name,
      units_sold: stats.units,
      revenue: stats.revenue.toFixed(2),
    }))
    .sort((a, b) => parseFloat(b.revenue) - parseFloat(a.revenue))
    .slice(0, 10);

  return {
    report_title: "Weekly Sales Report",
    date_range: `${startDate} to ${endDate}`,
    generated_at: new Date().toISOString().split("T")[0],
    total_revenue: totalRevenue.toFixed(2),
    total_orders: totalOrders,
    average_order_value: averageOrderValue.toFixed(2),
    daily_data: dailyData,
    top_products: topProducts,
    report_url: `https://dashboard.example.com/reports`,
  };
}

The key insight here is to do all the aggregation in application code rather than fighting with Supabase's limited aggregation support. For larger datasets, you could use a Supabase database function (a Postgres plpgsql function) to push the aggregation to the database layer. But for weekly reports with a few thousand rows, in-memory aggregation is fast and keeps the logic readable.

Step 3: Create a Report Template

Now build the Handlebars template that turns your data into a visually structured report. This template uses CSS grid for the summary cards, a styled table for the daily breakdown, a ranked list of top products, and a QR code that links to your live dashboard.

async function createReportTemplate() {
  const template = await df.templates.create({
    name: "Weekly Sales Report",
    html_content: `
      <html>
        <head>
          <style>
            * { margin: 0; padding: 0; box-sizing: border-box; }
            body {
              font-family: 'Helvetica Neue', Arial, sans-serif;
              color: #1a1a2e;
              padding: 50px;
              line-height: 1.6;
            }
            .report-header {
              display: flex;
              justify-content: space-between;
              align-items: flex-start;
              border-bottom: 3px solid #f97316;
              padding-bottom: 20px;
              margin-bottom: 30px;
            }
            .report-header h1 {
              font-size: 28px;
              font-weight: 700;
              color: #1a1a2e;
            }
            .report-header .meta {
              text-align: right;
              font-size: 13px;
              color: #666;
            }
            .summary-grid {
              display: grid;
              grid-template-columns: repeat(3, 1fr);
              gap: 20px;
              margin-bottom: 40px;
            }
            .summary-card {
              background: #f8f9fa;
              border-radius: 8px;
              padding: 20px;
              text-align: center;
            }
            .summary-card .label {
              font-size: 12px;
              text-transform: uppercase;
              color: #888;
              letter-spacing: 0.5px;
            }
            .summary-card .value {
              font-size: 32px;
              font-weight: 700;
              color: #f97316;
              margin-top: 6px;
            }
            h2 {
              font-size: 18px;
              margin-bottom: 15px;
              color: #1a1a2e;
            }
            table {
              width: 100%;
              border-collapse: collapse;
              margin-bottom: 40px;
              font-size: 14px;
            }
            thead th {
              text-align: left;
              padding: 10px 12px;
              background: #1a1a2e;
              color: #fff;
              font-weight: 600;
            }
            thead th:first-child { border-radius: 6px 0 0 0; }
            thead th:last-child { border-radius: 0 6px 0 0; }
            tbody td {
              padding: 10px 12px;
              border-bottom: 1px solid #eee;
            }
            tbody tr:nth-child(even) { background: #fafafa; }
            .top-products {
              margin-bottom: 40px;
            }
            .product-row {
              display: flex;
              justify-content: space-between;
              align-items: center;
              padding: 10px 0;
              border-bottom: 1px solid #eee;
            }
            .product-row .rank {
              width: 30px;
              height: 30px;
              background: #f97316;
              color: #fff;
              border-radius: 50%;
              display: flex;
              align-items: center;
              justify-content: center;
              font-weight: 700;
              font-size: 13px;
              margin-right: 14px;
            }
            .product-row .product-info {
              flex: 1;
            }
            .product-row .product-name {
              font-weight: 600;
            }
            .product-row .product-units {
              font-size: 12px;
              color: #888;
            }
            .product-row .product-revenue {
              font-weight: 700;
              color: #1a1a2e;
            }
            .footer-section {
              display: flex;
              justify-content: space-between;
              align-items: center;
              margin-top: 40px;
              padding-top: 20px;
              border-top: 1px solid #ddd;
            }
            .footer-section .note {
              font-size: 12px;
              color: #999;
              max-width: 400px;
            }
            .qr-section {
              text-align: center;
            }
            .qr-section .qr-label {
              font-size: 11px;
              color: #888;
              margin-top: 6px;
            }
          </style>
        </head>
        <body>
          <div class="report-header">
            <div>
              <h1>{{report_title}}</h1>
              <p style="color: #666; font-size: 14px;">{{date_range}}</p>
            </div>
            <div class="meta">
              <p>Generated: {{generated_at}}</p>
            </div>
          </div>

          <div class="summary-grid">
            <div class="summary-card">
              <div class="label">Total Revenue</div>
              <div class="value">\${{total_revenue}}</div>
            </div>
            <div class="summary-card">
              <div class="label">Total Orders</div>
              <div class="value">{{total_orders}}</div>
            </div>
            <div class="summary-card">
              <div class="label">Avg Order Value</div>
              <div class="value">\${{average_order_value}}</div>
            </div>
          </div>

          <h2>Daily Breakdown</h2>
          <table>
            <thead>
              <tr>
                <th>Date</th>
                <th>Orders</th>
                <th>Revenue</th>
              </tr>
            </thead>
            <tbody>
              {{#each daily_data}}
              <tr>
                <td>{{this.date}}</td>
                <td>{{this.orders}}</td>
                <td>\${{this.revenue}}</td>
              </tr>
              {{/each}}
            </tbody>
          </table>

          <div class="top-products">
            <h2>Top Products</h2>
            {{#each top_products}}
            <div class="product-row">
              <div class="rank">{{@index}}</div>
              <div class="product-info">
                <div class="product-name">{{this.name}}</div>
                <div class="product-units">{{this.units_sold}} units sold</div>
              </div>
              <div class="product-revenue">\${{this.revenue}}</div>
            </div>
            {{/each}}
          </div>

          <div class="footer-section">
            <div class="note">
              This report was automatically generated from live database records.
              Figures reflect completed orders only. Refunded and pending
              transactions are excluded.
            </div>
            <div class="qr-section">
              {{qr:{{report_url}}}}
              <div class="qr-label">Scan for live dashboard</div>
            </div>
          </div>
        </body>
      </html>
    `,
    schema: {
      report_title: "string",
      date_range: "string",
      generated_at: "string",
      total_revenue: "string",
      total_orders: "number",
      average_order_value: "string",
      daily_data: "array",
      top_products: "array",
      report_url: "string",
    },
  });

  console.log("Template created:", template.id);
  return template;
}

A few things to note about this template. The summary cards use a CSS grid with three equal columns. This renders cleanly in Chromium and produces consistent output across pages. The product ranking uses {{@index}} from Handlebars to display the position number automatically.

The QR code at the bottom uses DocuForge's {{qr:data}} placeholder syntax. Before rendering, DocuForge replaces this with an inline SVG. The QR code links to your live dashboard URL, so anyone who receives the printed report can scan it to see real-time data. This is particularly useful for reports that are printed and distributed in meetings.

You only need to create this template once. Save the returned template ID and reuse it for every report generation.

Step 4: Generate the Report PDF

With your data queried and your template created, generating the PDF is a single function call. Use df.fromTemplate() to merge the data into the template. Add a header with your company name and a footer with automatic page numbers.

const TEMPLATE_ID = "tmpl_your_report_template_id";

async function generateReport(startDate: string, endDate: string) {
  // Query and transform the data
  const reportData = await queryReportData(startDate, endDate);

  // Generate the PDF
  const result = await df.fromTemplate({
    template: TEMPLATE_ID,
    data: reportData,
    options: {
      format: "A4",
      orientation: "portrait",
      margin: { top: "35mm", right: "20mm", bottom: "25mm", left: "20mm" },
      printBackground: true,
      header: `
        <div style="font-size: 10px; color: #999; width: 100%; padding: 0 20mm;
                    display: flex; justify-content: space-between;">
          <span>Acme Corp</span>
          <span>Weekly Sales Report - Confidential</span>
        </div>
      `,
      footer: `
        <div style="font-size: 10px; color: #999; width: 100%; text-align: center;
                    padding: 0 20mm;">
          Page {{pageNumber}} of {{totalPages}}
        </div>
      `,
    },
  });

  console.log(`Report generated in ${result.generation_time_ms}ms`);
  console.log(`Pages: ${result.pages}`);
  console.log(`Size: ${(result.file_size / 1024).toFixed(1)} KB`);
  console.log(`URL: ${result.url}`);

  return result;
}

The {{pageNumber}} and {{totalPages}} placeholders in the footer are replaced at render time by the PDF engine. They are independent of the Handlebars variables in your template body. Make sure your top margin is at least 30-35mm to give the header enough room, and your bottom margin is at least 20-25mm for the footer. If the margins are too tight, the header or footer will overlap with your content.

The response gives you everything you need to work with the generated PDF. The url field points to the hosted PDF file. The id field (prefixed with gen_) lets you look up the generation later. The file_size is in bytes and generation_time_ms tells you how long the render took.

Step 5: Store the PDF URL Back in Supabase

Once the report is generated, store a reference back in your Supabase database. This creates an audit trail and makes it easy to build a report history page in your dashboard. Create a reports table with columns for the generation metadata.

First, set up the table. You can do this through the Supabase dashboard SQL editor:

create table reports (
  id uuid default gen_random_uuid() primary key,
  generation_id text not null,
  pdf_url text not null,
  report_type text not null default 'weekly_sales',
  date_range_start date not null,
  date_range_end date not null,
  total_revenue numeric,
  total_orders integer,
  pages integer,
  file_size integer,
  generation_time_ms integer,
  created_at timestamptz default now()
);

Then insert the record after each generation:

async function storeReportRecord(
  result: { id: string; url: string; pages: number; file_size: number; generation_time_ms: number },
  reportData: ReportData,
  startDate: string,
  endDate: string
) {
  const { error } = await supabase.from("reports").insert({
    generation_id: result.id,
    pdf_url: result.url,
    report_type: "weekly_sales",
    date_range_start: startDate,
    date_range_end: endDate,
    total_revenue: parseFloat(reportData.total_revenue),
    total_orders: reportData.total_orders,
    pages: result.pages,
    file_size: result.file_size,
    generation_time_ms: result.generation_time_ms,
  });

  if (error) throw new Error(`Failed to store report record: ${error.message}`);
  console.log("Report record saved to Supabase");
}

Now you can query the reports table to show a history of generated reports, link to the PDF URLs, or track generation performance over time. This is also useful for debugging: if a stakeholder says a report looks wrong, you can look up the exact generation ID and inspect it in your DocuForge dashboard.

Step 6: Automate with Supabase Edge Functions

Running this pipeline manually defeats the purpose. Supabase Edge Functions let you deploy a Deno-based serverless function that runs on a schedule. Create a new Edge Function that executes the full pipeline every Monday morning.

First, initialize the function:

supabase functions new generate-weekly-report

Then write the function in supabase/functions/generate-weekly-report/index.ts:

// supabase/functions/generate-weekly-report/index.ts
import { serve } from "https://deno.land/std@0.177.0/http/server.ts";
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

serve(async (req) => {
  try {
    const supabase = createClient(
      Deno.env.get("SUPABASE_URL")!,
      Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
    );

    // Calculate last week's date range
    const now = new Date();
    const endDate = new Date(now);
    endDate.setDate(now.getDate() - 1); // Yesterday
    const startDate = new Date(endDate);
    startDate.setDate(endDate.getDate() - 6); // 7 days back

    const startStr = startDate.toISOString().split("T")[0];
    const endStr = endDate.toISOString().split("T")[0];

    // Query orders
    const { data: orders, error } = await supabase
      .from("orders")
      .select("*")
      .gte("created_at", startStr)
      .lte("created_at", endStr)
      .eq("status", "completed");

    if (error) throw error;

    const totalRevenue = orders.reduce((sum: number, o: any) => sum + o.total_price, 0);
    const totalOrders = orders.length;

    // Call DocuForge API directly (no npm SDK in Deno)
    const apiKey = Deno.env.get("DOCUFORGE_API_KEY")!;
    const templateId = Deno.env.get("REPORT_TEMPLATE_ID")!;

    const generateResponse = await fetch("https://api.docuforge.com/v1/generate", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template: templateId,
        data: {
          report_title: "Weekly Sales Report",
          date_range: `${startStr} to ${endStr}`,
          generated_at: now.toISOString().split("T")[0],
          total_revenue: totalRevenue.toFixed(2),
          total_orders: totalOrders,
          average_order_value: (totalRevenue / totalOrders).toFixed(2),
          daily_data: [], // Build from orders as shown in Step 2
          top_products: [], // Build from orders as shown in Step 2
          report_url: "https://dashboard.example.com/reports",
        },
        options: {
          format: "A4",
          margin: { top: "35mm", right: "20mm", bottom: "25mm", left: "20mm" },
          printBackground: true,
          footer: '<div style="font-size:10px;color:#999;width:100%;text-align:center;">Page {{pageNumber}} of {{totalPages}}</div>',
        },
      }),
    });

    const result = await generateResponse.json();

    // Store the record
    await supabase.from("reports").insert({
      generation_id: result.id,
      pdf_url: result.url,
      report_type: "weekly_sales",
      date_range_start: startStr,
      date_range_end: endStr,
      total_revenue: totalRevenue,
      total_orders: totalOrders,
      pages: result.pages,
      file_size: result.file_size,
      generation_time_ms: result.generation_time_ms,
    });

    return new Response(JSON.stringify({ success: true, url: result.url }), {
      headers: { "Content-Type": "application/json" },
    });
  } catch (err) {
    return new Response(JSON.stringify({ error: err.message }), {
      status: 500,
      headers: { "Content-Type": "application/json" },
    });
  }
});

Deploy the function and set the required secrets:

supabase functions deploy generate-weekly-report
supabase secrets set DOCUFORGE_API_KEY=df_live_your_key
supabase secrets set REPORT_TEMPLATE_ID=tmpl_your_id

To run it on a schedule, set up a cron job using the pg_cron extension in Supabase. In the SQL editor:

select cron.schedule(
  'weekly-sales-report',
  '0 8 * * 1',  -- Every Monday at 8:00 AM UTC
  $$
  select net.http_post(
    url := 'https://your-project.supabase.co/functions/v1/generate-weekly-report',
    headers := '{"Authorization": "Bearer your-anon-key"}'::jsonb
  );
  $$
);

This triggers the Edge Function every Monday at 8 AM. The report covers the previous seven days, generates a PDF, and stores the result. No manual intervention required.

Step 7: Batch Reports for Multiple Clients

If you run a multi-tenant platform, you need to generate separate reports for each client. Doing this sequentially is slow. The DocuForge batch API lets you queue all reports at once and get notified when they are done.

async function generateClientReports(startDate: string, endDate: string) {
  // Fetch all active clients
  const { data: clients, error } = await supabase
    .from("clients")
    .select("id, name, slug")
    .eq("status", "active");

  if (error) throw error;

  // Query each client's data and build batch items
  const items = await Promise.all(
    clients.map(async (client) => {
      const { data: orders } = await supabase
        .from("orders")
        .select("*")
        .eq("client_id", client.id)
        .gte("created_at", startDate)
        .lte("created_at", endDate)
        .eq("status", "completed");

      const totalRevenue = (orders || []).reduce(
        (sum, o) => sum + o.total_price,
        0
      );

      return {
        template: TEMPLATE_ID,
        data: {
          report_title: `${client.name} - Weekly Sales Report`,
          date_range: `${startDate} to ${endDate}`,
          generated_at: new Date().toISOString().split("T")[0],
          total_revenue: totalRevenue.toFixed(2),
          total_orders: (orders || []).length,
          average_order_value:
            orders && orders.length > 0
              ? (totalRevenue / orders.length).toFixed(2)
              : "0.00",
          daily_data: [], // Build per-client daily breakdown
          top_products: [], // Build per-client product ranking
          report_url: `https://dashboard.example.com/${client.slug}/reports`,
        },
        options: {
          format: "A4",
          margin: { top: "35mm", right: "20mm", bottom: "25mm", left: "20mm" },
          printBackground: true,
        },
      };
    })
  );

  // Submit all reports as a single batch
  const batch = await df.batch({
    items,
    webhook: "https://your-app.com/api/webhooks/batch-complete",
  });

  console.log(`Batch submitted: ${batch.batch_id}`);
  console.log(`Total reports: ${batch.total}`);
  console.log(`Status: ${batch.status}`);

  // Store batch metadata
  await supabase.from("report_batches").insert({
    batch_id: batch.batch_id,
    total_reports: batch.total,
    date_range_start: startDate,
    date_range_end: endDate,
    client_ids: clients.map((c) => c.id),
  });

  return batch;
}

The df.batch() call returns immediately with HTTP 202. The response includes a batch_id, the total number of reports queued, and an array of generations with each item's id and index. DocuForge processes the jobs concurrently on its side using a BullMQ worker pool with retries and exponential backoff.

When all reports finish, DocuForge sends a POST request to your webhook URL. Your webhook handler can then update the batch status in Supabase, notify clients via email, or trigger downstream workflows. For a batch of 50 client reports, this approach is dramatically faster than generating them one at a time.

You can also poll individual generation status using df.getGeneration(id) if you prefer polling over webhooks.

Going Further

You now have a fully automated reporting pipeline: Supabase data in, polished PDFs out, with scheduling and multi-client batch support. Here are some natural next steps:

Automate Stripe invoices -- Generate PDF invoices on every successful Stripe payment and email them to customers.
Generate PDFs in Next.js -- Build a dashboard front end that lets users trigger report generation on demand.
Page layout guide -- Fine-tune margins, headers, footers, and multi-page layouts for professional documents.

Check out the full API reference for additional features like PDF merging, splitting, password protection, and form filling.

How to Add PDF Export to Any React App

Fred T — Thu, 19 Mar 2026 17:00:00 +0000

Introduction

Every data-heavy React application eventually gets the same feature request: "Can I download this as a PDF?" Whether it is an analytics dashboard, an invoice screen, or a student report card, users expect a clean, one-click export that looks just as polished on paper as it does on screen.

DocuForge gives you three ways to satisfy that request, and you can mix them within the same project:

HTML string generation -- capture rendered HTML from the DOM and send it to df.generate(). Fastest to wire up, best for simple pages.
React component to PDF with fromReact() -- send a JSX/TSX source string along with data as props. The component is rendered server-side by DocuForge, giving you full control over the PDF layout without coupling it to your UI.
@docuforge/react component library -- purpose-built components like Document, Page, Table, and Watermark that map directly to PDF concepts. Combine them with fromReact() for pixel-perfect results.

This tutorial walks through all three approaches, building up to a complete dashboard export feature you can drop into any React app.

Approach 1: HTML String Generation

The simplest path is to grab HTML that is already on the page and send it to DocuForge. This works well when your existing UI is close to what you want the PDF to look like.

Server API Route

Create an API route that accepts an HTML string and returns a PDF URL:

```ts title="app/api/pdf/route.ts"
import { DocuForge } from "docuforge";

const df = new DocuForge(process.env.DOCUFORGE_API_KEY!);

export async function POST(req: Request) {
const { html } = await req.json();

const result = await df.generate({
html,
options: {
format: "A4",
margin: "20mm",
printBackground: true,
},
});

return Response.json({ url: result.url });
}




### Client: Capture and Send

On the client, grab the `innerHTML` of the container you want to export:



```tsx title="components/ExportButton.tsx"
"use client";

import { useState } from "react";

export function ExportButton({ targetId }: { targetId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleExport() {
    setLoading(true);
    const element = document.getElementById(targetId);
    if (!element) return;

    const res = await fetch("/api/pdf", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ html: element.innerHTML }),
    });

    const { url } = await res.json();
    window.open(url, "_blank");
    setLoading(false);
  }

  return (
    <button onClick={handleExport} disabled={loading}>
      {loading ? "Generating..." : "Export to PDF"}
    </button>
  );
}

This approach has limitations. The captured HTML will not include your bundled CSS unless you inline it, interactive components like dropdowns and tabs will export in whatever state they happen to be in, and responsive layouts designed for wide screens may not translate well to an A4 page. For anything beyond a simple content block, Approach 2 is a better fit.

Approach 2: React Component to PDF with fromReact()

The fromReact() method takes a JSX/TSX source string containing an export default function component. DocuForge transpiles the component server-side, injects the data object you provide as props, renders it to static HTML, and converts the result to PDF. This means you can write a dedicated PDF layout component that is completely independent of your screen UI.

Define the PDF Component

Write your component as a plain string. It receives the data prop automatically:

``ts title="lib/pdf-templates/sales-report.ts" export const salesReportComponent =
import React from "react";

export default function SalesReport({ data }) {
const { title, rows, generatedAt } = data;

return (

{title}

Generated: {generatedAt}

  <table style={{ width: "100%", borderCollapse: "collapse", marginTop: "24px" }}>
    <thead>
      <tr style={{ backgroundColor: "#f4f4f4" }}>
        <th style={{ textAlign: "left", padding: "8px", borderBottom: "1px solid #ddd" }}>Product</th>
        <th style={{ textAlign: "right", padding: "8px", borderBottom: "1px solid #ddd" }}>Units</th>
        <th style={{ textAlign: "right", padding: "8px", borderBottom: "1px solid #ddd" }}>Revenue</th>
      </tr>
    </thead>
    <tbody>
      {rows.map((row, i) => (
        <tr key={i} style={{ backgroundColor: i % 2 === 0 ? "#fff" : "#fafafa" }}>
          <td style={{ padding: "8px", borderBottom: "1px solid #eee" }}>{row.product}</td>
          <td style={{ padding: "8px", borderBottom: "1px solid #eee", textAlign: "right" }}>{row.units}</td>
          <td style={{ padding: "8px", borderBottom: "1px solid #eee", textAlign: "right" }}>{row.revenue}</td>
        </tr>
      ))}
    </tbody>
  </table>
</div>

);
}
`;




### Generate the PDF

Pass the component source and data to `fromReact()`:



```ts title="app/api/report/route.ts"
import { DocuForge } from "docuforge";
import { salesReportComponent } from "@/lib/pdf-templates/sales-report";

const df = new DocuForge(process.env.DOCUFORGE_API_KEY!);

export async function POST(req: Request) {
  const { rows } = await req.json();

  const result = await df.fromReact({
    react: salesReportComponent,
    data: {
      title: "Q1 Sales Report",
      rows,
      generatedAt: new Date().toLocaleDateString(),
    },
    styles: `
      @page { margin: 20mm; }
      body { -webkit-print-color-adjust: exact; }
    `,
    options: {
      format: "A4",
      printBackground: true,
    },
  });

  return Response.json({
    url: result.url,
    pages: result.pages,
    generationTime: result.generation_time_ms,
  });
}

The key advantage is separation of concerns. Your screen UI can use any component library and layout system you like, while the PDF component is purpose-built for a printed page. You also get server-side rendering out of the box -- no browser required on your end.

Using @docuforge/react Components

For structured documents with recurring elements like headers, footers, tables, and watermarks, the @docuforge/react component library provides pre-built primitives that handle PDF-specific concerns for you.

Install the package:

npm install @docuforge/react

Building a Document

The library is organized around a Document > Page hierarchy. Each Page maps to a physical page in the output PDF:

``ts title="lib/pdf-templates/invoice.ts" export const invoiceComponent =
import React from "react";
import {
Document,
Page,
Header,
Footer,
Table,
Watermark,
} from "@docuforge/react";

export default function Invoice({ data }) {
const { invoiceNumber, customer, items, total, isPaid } = data;

const columns = [
{ key: "description", header: "Description", width: "50%" },
{ key: "quantity", header: "Qty", width: "15%", align: "center" },
{
key: "unitPrice",
header: "Unit Price",
width: "15%",
align: "right",
render: (value) => "$" + value.toFixed(2),
},
{
key: "total",
header: "Total",
width: "20%",
align: "right",
render: (value) => "$" + value.toFixed(2),
},
];

return (

INVOICE

{invoiceNumber}

Acme Corp

123 Business Ave

San Francisco, CA 94102

    <div style={{ marginTop: "24px" }}>
      <h3 style={{ marginBottom: "4px" }}>Bill To:</h3>
      <p>{customer.name}</p>
      <p style={{ color: "#666" }}>{customer.email}</p>
    </div>

    <Table
      data={items}
      columns={columns}
      striped
      bordered
      style={{ marginTop: "24px" }}
    />

    <div style={{ textAlign: "right", marginTop: "16px", fontSize: "18px" }}>
      <strong>Total: ${"{total.toFixed(2)}"}</strong>
    </div>

    {isPaid && <Watermark text="PAID" color="#22c55e" opacity={0.08} />}

    <Footer style={{ borderTop: "1px solid #eee", paddingTop: "8px", fontSize: "11px", color: "#999" }}>
      <p>Thank you for your business. Payment due within 30 days.</p>
    </Footer>
  </Page>
</Document>

);
}
`;




### Component Breakdown

A few things to note about the components used above:

- **`Document`** wraps the entire output. The `title` prop sets the PDF metadata title. You can also pass a `styles` prop with a global CSS string.
- **`Page`** defines a single page. The `size` prop accepts `"A4"`, `"Letter"`, or `"Legal"`. The `margin` prop defaults to `"20mm"` and accepts any CSS length value.
- **`Header`** and **`Footer`** are positioned at the top and bottom of every page. Footer uses absolute positioning to anchor itself to the page bottom.
- **`Table`** takes a `data` array and a `columns` configuration. Each column specifies a `key` (matching the data field), a `header` label, and optionally `width`, `align`, and a `render` function for custom formatting.
- **`Watermark`** overlays rotated text across the page. The `opacity` defaults to `0.08` and `angle` to `-45` degrees, producing a subtle diagonal watermark.

## Wire Up the Download Button

With the PDF template defined, you need a client component that triggers the generation and handles the file download. Here is a reusable pattern:



```tsx title="components/DownloadPDFButton.tsx"
"use client";

import { useState } from "react";

interface DownloadPDFButtonProps {
  endpoint: string;
  payload: Record<string, unknown>;
  filename?: string;
  children?: React.ReactNode;
}

export function DownloadPDFButton({
  endpoint,
  payload,
  filename = "document.pdf",
  children,
}: DownloadPDFButtonProps) {
  const [loading, setLoading] = useState(false);

  async function handleDownload() {
    setLoading(true);

    try {
      const res = await fetch(endpoint, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(payload),
      });

      if (!res.ok) {
        throw new Error("PDF generation failed");
      }

      const { url } = await res.json();

      // Trigger browser download
      const link = document.createElement("a");
      link.href = url;
      link.download = filename;
      document.body.appendChild(link);
      link.click();
      document.body.removeChild(link);
    } catch (err) {
      console.error("Download failed:", err);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button
      onClick={handleDownload}
      disabled={loading}
      style={{
        padding: "8px 16px",
        backgroundColor: loading ? "#ccc" : "#F97316",
        color: "#fff",
        border: "none",
        borderRadius: "6px",
        cursor: loading ? "not-allowed" : "pointer",
        fontSize: "14px",
      }}
    >
      {loading ? "Generating PDF..." : children || "Download PDF"}
    </button>
  );
}

Usage in a page component is straightforward:

<DownloadPDFButton
  endpoint="/api/report"
  payload={{ rows: salesData }}
  filename="Q1-Sales-Report.pdf"
>
  Export Sales Report
</DownloadPDFButton>

The button handles the loading state, error handling, and download trigger. When the user clicks, it sends the data to your API route, receives the PDF URL from DocuForge, and initiates the browser download.

Styling for PDF

PDF rendering differs from screen rendering in a few important ways. DocuForge uses Chromium under the hood, so standard CSS works, but there are guidelines to follow for reliable output.

The `styles` Prop

Both df.generate() (via html) and df.fromReact() accept a styles prop or inline CSS. When using fromReact(), pass a CSS string via the styles parameter:

const result = await df.fromReact({
  react: myComponent,
  data: reportData,
  styles: `
    body {
      font-family: "Helvetica Neue", Arial, sans-serif;
      font-size: 12px;
      color: #333;
      line-height: 1.5;
    }

    table { page-break-inside: avoid; }

    h1, h2, h3 { page-break-after: avoid; }

    .page-break { page-break-before: always; }
  `,
  options: {
    format: "A4",
    printBackground: true,
  },
});

Key Tips

Always set printBackground: true if your design uses background colors or gradients. Chromium strips backgrounds in print mode by default.
Avoid viewport-relative units like vh and vw. These are unreliable in a headless context. Use mm, in, px, or % instead.
Use page-break-inside: avoid on elements like table rows and cards that should not be split across pages.
Use page-break-before: always when you need to force a new page at a specific point.
Stick to web-safe fonts or embed font files via @font-face in your styles string. System fonts like Helvetica, Arial, Georgia, and Courier are universally available.
Set explicit widths on tables and columns rather than relying on auto-layout. This ensures consistent rendering regardless of content length.

Complete Example: Dashboard Report Export

Here is a full working example that ties everything together. A dashboard page displays metrics and a data table on screen, and a button exports the same data as a professionally formatted PDF using @docuforge/react components.

The PDF Template

``ts title="lib/pdf-templates/dashboard-report.ts" export const dashboardReportComponent =
import React from "react";
import { Document, Page, Header, Footer, Table, Grid } from "@docuforge/react";

export default function DashboardReport({ data }) {
const { title, period, metrics, transactions } = data;

return (

{title}

{period}

Generated on {new Date().toLocaleDateString()}

    <Grid columns={4} gap="16px">
      {metrics.map((metric, i) => (
        <div
          key={i}
          style={{
            border: "1px solid #e5e5e5",
            borderRadius: "8px",
            padding: "16px",
            textAlign: "center",
          }}
        >
          <p style={{ margin: 0, fontSize: "12px", color: "#666", textTransform: "uppercase" }}>
            {metric.label}
          </p>
          <p style={{ margin: "8px 0 0", fontSize: "24px", fontWeight: 700 }}>
            {metric.value}
          </p>
        </div>
      ))}
    </Grid>

    <h2 style={{ fontSize: "16px", marginTop: "32px", marginBottom: "12px" }}>
      Recent Transactions
    </h2>

    <Table
      data={transactions}
      columns={columns}
      striped
      bordered
    />

    <Footer style={{ borderTop: "1px solid #e5e5e5", paddingTop: "8px", fontSize: "10px", color: "#999" }}>
      <div style={{ display: "flex", justifyContent: "space-between" }}>
        <span>Confidential -- Internal Use Only</span>
        <span>DocuForge Dashboard Export</span>
      </div>
    </Footer>
  </Page>
</Document>

);
}
`;




### The API Route



```ts title="app/api/dashboard-report/route.ts"
import { DocuForge } from "docuforge";
import { dashboardReportComponent } from "@/lib/pdf-templates/dashboard-report";

const df = new DocuForge(process.env.DOCUFORGE_API_KEY!);

export async function POST(req: Request) {
  const { title, period, metrics, transactions } = await req.json();

  const result = await df.fromReact({
    react: dashboardReportComponent,
    data: { title, period, metrics, transactions },
    options: {
      format: "A4",
      margin: "0mm",
      printBackground: true,
    },
  });

  return Response.json({
    id: result.id,
    url: result.url,
    pages: result.pages,
    fileSize: result.file_size,
    generationTime: result.generation_time_ms,
  });
}

The Dashboard Page

```tsx title="app/dashboard/page.tsx"
"use client";

import { DownloadPDFButton } from "@/components/DownloadPDFButton";

const metrics = [
{ label: "Revenue", value: "$48,290" },
{ label: "Orders", value: "1,247" },
{ label: "Avg. Order", value: "$38.72" },
{ label: "Conversion", value: "3.2%" },
];

const transactions = [
{ date: "2026-03-15", description: "Enterprise license - Acme Corp", amount: 12000, status: "completed" },
{ date: "2026-03-14", description: "Pro plan upgrade - Jane Smith", amount: 49, status: "completed" },
{ date: "2026-03-14", description: "Starter plan - New signup", amount: 19, status: "pending" },
{ date: "2026-03-13", description: "Enterprise license - Globex Inc", amount: 12000, status: "completed" },
{ date: "2026-03-12", description: "Refund - John Doe", amount: -49, status: "refunded" },
];

export default function DashboardPage() {
return (

Dashboard

endpoint="/api/dashboard-report"
payload={{
title: "Monthly Dashboard Report",
period: "March 1 - March 31, 2026",
metrics,
transactions,
}}
filename="dashboard-report-march-2026.pdf"
>
Export Report

  {/* Screen UI for metrics and transactions goes here */}
</div>

);
}




When the user clicks "Export Report," the button component sends the metrics and transaction data to the API route, which passes everything to DocuForge via `fromReact()`. DocuForge renders the `@docuforge/react` components into a structured PDF with a branded header, metric cards in a grid, a striped and bordered data table, and a footer -- all generated in under two seconds.

## Going Further

You now have the tools to add PDF export to any React application, from a quick HTML capture to a fully designed document with `@docuforge/react` components. Here are some next steps to explore:

- **[Generating PDFs in Next.js with Server Actions](https://getdocuforge.dev/blog/generate-pdfs-nextjs-docuforge)** -- deeper integration with the App Router and Server Actions pattern.
- **[Page Layout and Multi-Page Documents](https://getdocuforge.dev/blog/pdf-page-breaks-headers-footers-guide)** -- advanced control over page breaks, headers that repeat across pages, and landscape orientation.
- **Batch generation** -- use `df.batch()` to generate hundreds of PDFs asynchronously when you need to export reports for every customer at once.
- **Webhook notifications** -- pass a `webhook` URL to `df.generate()` or `df.fromReact()` to receive a callback when long-running generations complete.

Check out the [DocuForge documentation](https://docs.getdocuforge.dev) for the full API reference and more examples.

Build an Invoice System with Stripe + DocuForge

Fred T — Thu, 19 Mar 2026 13:00:00 +0000

Introduction

Stripe is the de facto standard for processing payments online. It handles charges, subscriptions, refunds, and dozens of other financial operations with remarkable reliability. But when a payment succeeds, your customers expect a proper invoice -- a formatted PDF they can download, forward to their accountant, or file away for tax season. Stripe's built-in invoices cover the basics, but they offer limited control over branding, layout, and the finer details that make your business look polished.

That is where DocuForge comes in. DocuForge is a PDF generation API that accepts HTML templates and structured data, then returns pixel-perfect PDFs. By wiring Stripe payment events to DocuForge templates, you get a fully automated invoice pipeline: a customer pays, Stripe fires a webhook, your server maps the payment data into a Handlebars template, DocuForge renders the PDF, and you email it to the customer. No manual steps, no cron jobs, no brittle HTML-to-PDF libraries running on your own infrastructure.

In this tutorial, you will build exactly that system. By the end, you will have a production-ready webhook handler that listens for invoice.payment_succeeded events from Stripe, generates a branded PDF invoice through DocuForge, and emails it to the customer using Resend. You will also learn how to use batch generation for monthly billing runs. The full source code is included at the end.

What you will need:

A Stripe account with a webhook endpoint configured
A DocuForge API key (sign up at docuforge.com)
Node.js 18+ and TypeScript
A Resend API key for sending emails

Architecture Overview

The system follows a straightforward event-driven flow. No polling, no scheduled jobs -- Stripe pushes events to your server the moment something happens.

Stripe Payment Succeeded
        |
        v
  Webhook Endpoint (POST /api/webhooks/stripe)
        |
        v
  Verify Stripe Signature
        |
        v
  Extract Invoice Data (line items, customer, amounts)
        |
        v
  DocuForge fromTemplate() --> PDF URL
        |
        v
  Store PDF URL in Database
        |
        v
  Email Invoice to Customer (Resend)

The tech stack is deliberately minimal. You will use Next.js API routes for the webhook handler, the official Stripe Node SDK for signature verification and data extraction, the DocuForge TypeScript SDK for PDF generation, and Resend for transactional email. If you prefer Express or Fastify, the core logic is identical -- only the route definition changes.

All communication is synchronous except for the optional batch generation path, which uses DocuForge's async queue and webhook callbacks.

Step 1: Create the Invoice Template

Before handling any Stripe events, you need an invoice template stored in DocuForge. Templates use Handlebars syntax for dynamic data and standard HTML/CSS for layout. Once created, you reference the template by ID and pass in different data for each invoice.

Install the dependencies first:

npm install docuforge stripe resend

Here is a complete invoice template with professional styling:

import DocuForge from "docuforge";

const df = new DocuForge(process.env.DOCUFORGE_API_KEY!);

const invoiceTemplate = await df.templates.create({
  name: "Stripe Invoice",
  html_content: `
    <!DOCTYPE html>
    <html>
    <head>
      <style>
        * { margin: 0; padding: 0; box-sizing: border-box; }
        body {
          font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
          color: #1a1a1a;
          padding: 60px;
          font-size: 14px;
          line-height: 1.6;
        }
        .header {
          display: flex;
          justify-content: space-between;
          align-items: flex-start;
          margin-bottom: 50px;
        }
        .company-name {
          font-size: 28px;
          font-weight: 700;
          color: #111827;
        }
        .company-details {
          color: #6b7280;
          font-size: 13px;
          margin-top: 4px;
        }
        .invoice-badge {
          background: #f0fdf4;
          color: #16a34a;
          padding: 6px 16px;
          border-radius: 20px;
          font-weight: 600;
          font-size: 13px;
          text-transform: uppercase;
          letter-spacing: 0.5px;
        }
        .invoice-meta {
          display: grid;
          grid-template-columns: 1fr 1fr;
          gap: 40px;
          margin-bottom: 40px;
          padding: 30px;
          background: #f9fafb;
          border-radius: 8px;
        }
        .meta-label {
          font-size: 11px;
          text-transform: uppercase;
          letter-spacing: 0.8px;
          color: #9ca3af;
          font-weight: 600;
          margin-bottom: 4px;
        }
        .meta-value {
          font-size: 15px;
          font-weight: 500;
          color: #111827;
        }
        table {
          width: 100%;
          border-collapse: collapse;
          margin-bottom: 30px;
        }
        thead th {
          text-align: left;
          padding: 12px 16px;
          font-size: 11px;
          text-transform: uppercase;
          letter-spacing: 0.8px;
          color: #6b7280;
          font-weight: 600;
          border-bottom: 2px solid #e5e7eb;
        }
        thead th:last-child { text-align: right; }
        tbody td {
          padding: 14px 16px;
          border-bottom: 1px solid #f3f4f6;
          color: #374151;
        }
        tbody td:last-child {
          text-align: right;
          font-variant-numeric: tabular-nums;
        }
        .totals {
          display: flex;
          justify-content: flex-end;
          margin-top: 10px;
        }
        .totals-table {
          width: 280px;
        }
        .totals-row {
          display: flex;
          justify-content: space-between;
          padding: 8px 0;
          font-size: 14px;
          color: #6b7280;
        }
        .totals-row.total {
          border-top: 2px solid #111827;
          margin-top: 8px;
          padding-top: 12px;
          font-size: 18px;
          font-weight: 700;
          color: #111827;
        }
        .payment-note {
          margin-top: 50px;
          padding: 20px;
          background: #f0fdf4;
          border-left: 4px solid #16a34a;
          border-radius: 0 8px 8px 0;
          color: #166534;
          font-size: 13px;
        }
        .footer-note {
          margin-top: 40px;
          text-align: center;
          color: #9ca3af;
          font-size: 12px;
        }
      </style>
    </head>
    <body>
      <div class="header">
        <div>
          <div class="company-name">{{company_name}}</div>
          <div class="company-details">{{company_address}}</div>
          <div class="company-details">{{company_email}}</div>
        </div>
        <div class="invoice-badge">Paid</div>
      </div>

      <div class="invoice-meta">
        <div>
          <div class="meta-label">Invoice Number</div>
          <div class="meta-value">{{invoice_number}}</div>
          <div style="margin-top: 16px;">
            <div class="meta-label">Date Issued</div>
            <div class="meta-value">{{date}}</div>
          </div>
        </div>
        <div>
          <div class="meta-label">Bill To</div>
          <div class="meta-value">{{customer_name}}</div>
          <div style="color: #6b7280; font-size: 13px; margin-top: 2px;">
            {{customer_email}}
          </div>
          {{#if customer_address}}
          <div style="color: #6b7280; font-size: 13px; margin-top: 2px;">
            {{customer_address}}
          </div>
          {{/if}}
        </div>
      </div>

      <table>
        <thead>
          <tr>
            <th>Description</th>
            <th>Qty</th>
            <th>Unit Price</th>
            <th>Amount</th>
          </tr>
        </thead>
        <tbody>
          {{#each line_items}}
          <tr>
            <td>{{this.description}}</td>
            <td>{{this.quantity}}</td>
            <td>{{this.unit_price}}</td>
            <td>{{this.amount}}</td>
          </tr>
          {{/each}}
        </tbody>
      </table>

      <div class="totals">
        <div class="totals-table">
          <div class="totals-row">
            <span>Subtotal</span>
            <span>{{subtotal}}</span>
          </div>
          {{#if tax}}
          <div class="totals-row">
            <span>Tax</span>
            <span>{{tax}}</span>
          </div>
          {{/if}}
          <div class="totals-row total">
            <span>Total</span>
            <span>{{amount_due}}</span>
          </div>
        </div>
      </div>

      <div class="payment-note">
        Payment of {{amount_due}} received on {{date}}. Thank you for your business.
      </div>

      <div class="footer-note">
        {{company_name}} &middot; {{company_email}}
      </div>
    </body>
    </html>
  `,
  schema: {
    company_name: { type: "string", required: true },
    company_address: { type: "string", required: true },
    company_email: { type: "string", required: true },
    customer_name: { type: "string", required: true },
    customer_email: { type: "string", required: true },
    customer_address: { type: "string", required: false },
    invoice_number: { type: "string", required: true },
    date: { type: "string", required: true },
    line_items: {
      type: "array",
      required: true,
      items: {
        description: { type: "string" },
        quantity: { type: "number" },
        unit_price: { type: "string" },
        amount: { type: "string" },
      },
    },
    subtotal: { type: "string", required: true },
    tax: { type: "string", required: false },
    amount_due: { type: "string", required: true },
  },
});

// Save this ID -- you will reference it in the webhook handler
console.log("Template created:", invoiceTemplate.id);
// Example: tmpl_a1b2c3d4e5f6

Run this script once to create the template. Store the returned template ID in your environment variables as INVOICE_TEMPLATE_ID. The schema definition is optional but useful -- it documents what data the template expects and enables validation when generating PDFs.

Step 2: Set Up Stripe Webhook Handler

Stripe webhooks are HTTP POST requests signed with a secret so you can verify they actually came from Stripe. The critical event for invoice generation is invoice.payment_succeeded, which fires after a successful charge on a subscription or one-off invoice.

First, configure your Stripe webhook in the Stripe Dashboard (Developers > Webhooks). Point it to your endpoint URL and select the invoice.payment_succeeded event. Copy the webhook signing secret.

Here is the webhook handler:

// app/api/webhooks/stripe/route.ts (Next.js App Router)
import { NextRequest, NextResponse } from "next/server";
import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2024-12-18.acacia",
});

export async function POST(req: NextRequest) {
  const body = await req.text();
  const signature = req.headers.get("stripe-signature");

  if (!signature) {
    return NextResponse.json(
      { error: "Missing stripe-signature header" },
      { status: 400 }
    );
  }

  let event: Stripe.Event;

  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err) {
    console.error("Webhook signature verification failed:", err);
    return NextResponse.json(
      { error: "Invalid signature" },
      { status: 400 }
    );
  }

  if (event.type === "invoice.payment_succeeded") {
    const invoice = event.data.object as Stripe.Invoice;
    await handleInvoicePaid(invoice);
  }

  // Acknowledge receipt immediately -- Stripe retries on timeout
  return NextResponse.json({ received: true });
}

async function handleInvoicePaid(invoice: Stripe.Invoice) {
  const templateData = mapStripeInvoice(invoice);
  const pdfUrl = await generateInvoicePdf(templateData);
  await emailInvoice(invoice.customer_email!, pdfUrl, templateData);
}

Now the data mapping function. Stripe amounts are in cents, so you need to convert them. Line item descriptions, quantities, and amounts need to be extracted and formatted:

interface InvoiceTemplateData {
  company_name: string;
  company_address: string;
  company_email: string;
  customer_name: string;
  customer_email: string;
  customer_address?: string;
  invoice_number: string;
  date: string;
  line_items: {
    description: string;
    quantity: number;
    unit_price: string;
    amount: string;
  }[];
  subtotal: string;
  tax?: string;
  amount_due: string;
}

function formatCents(cents: number, currency: string): string {
  return new Intl.NumberFormat("en-US", {
    style: "currency",
    currency: currency.toUpperCase(),
  }).format(cents / 100);
}

function mapStripeInvoice(invoice: Stripe.Invoice): InvoiceTemplateData {
  const currency = invoice.currency;

  const lineItems = (invoice.lines?.data ?? []).map((line) => ({
    description: line.description ?? "Service",
    quantity: line.quantity ?? 1,
    unit_price: formatCents(line.unit_amount_excluding_tax
      ? parseInt(line.unit_amount_excluding_tax)
      : (line.amount / (line.quantity ?? 1)), currency),
    amount: formatCents(line.amount, currency),
  }));

  return {
    company_name: process.env.COMPANY_NAME ?? "Your Company",
    company_address: process.env.COMPANY_ADDRESS ?? "",
    company_email: process.env.COMPANY_EMAIL ?? "",
    customer_name: invoice.customer_name ?? "Customer",
    customer_email: invoice.customer_email ?? "",
    customer_address: invoice.customer_address?.line1
      ? [
          invoice.customer_address.line1,
          invoice.customer_address.city,
          invoice.customer_address.state,
          invoice.customer_address.postal_code,
        ]
          .filter(Boolean)
          .join(", ")
      : undefined,
    invoice_number: invoice.number ?? invoice.id,
    date: new Date((invoice.status_transitions?.paid_at ?? Date.now() / 1000) * 1000)
      .toLocaleDateString("en-US", {
        year: "numeric",
        month: "long",
        day: "numeric",
      }),
    line_items: lineItems,
    subtotal: formatCents(invoice.subtotal, currency),
    tax: invoice.tax ? formatCents(invoice.tax, currency) : undefined,
    amount_due: formatCents(invoice.amount_paid, currency),
  };
}

The mapping function handles the common edge cases: missing customer names, null quantities, and address formatting. The formatCents helper uses Intl.NumberFormat so it works correctly with any currency Stripe supports.

Step 3: Generate the Invoice PDF

With the template created and the Stripe data mapped, generating the PDF is a single SDK call. The fromTemplate method accepts the template ID and a data object that fills in the Handlebars placeholders.

import DocuForge from "docuforge";

const df = new DocuForge(process.env.DOCUFORGE_API_KEY!);

async function generateInvoicePdf(data: InvoiceTemplateData): Promise<string> {
  const pdf = await df.fromTemplate({
    template: process.env.INVOICE_TEMPLATE_ID!,
    data,
    options: {
      format: "A4",
      margin: {
        top: "20mm",
        right: "20mm",
        bottom: "30mm",
        left: "20mm",
      },
      printBackground: true,
      footer: `
        <div style="width: 100%; text-align: center; font-size: 10px; color: #9ca3af;">
          Page {{pageNumber}} of {{totalPages}}
        </div>
      `,
    },
  });

  console.log(`Invoice PDF generated: ${pdf.id}`);
  console.log(`  URL: ${pdf.url}`);
  console.log(`  Pages: ${pdf.pages}, Size: ${pdf.file_size} bytes`);
  console.log(`  Rendered in ${pdf.generation_time_ms}ms`);

  // Store the generation record in your database
  // await db.invoicePdfs.create({
  //   stripeInvoiceId: data.invoice_number,
  //   generationId: pdf.id,
  //   pdfUrl: pdf.url,
  //   createdAt: new Date(),
  // });

  return pdf.url;
}

The response includes everything you need: a hosted URL where the PDF can be downloaded, the page count, file size, and how long the render took. DocuForge hosts the file for you, so there is no need to set up your own storage bucket unless you want to.

The footer uses the {{pageNumber}} and {{totalPages}} interpolation variables that DocuForge injects automatically. These work independently of the Handlebars template variables in the body -- they are processed by the PDF renderer at print time.

If you want to store the PDF yourself rather than using the hosted URL, pass output: 'base64' and the response will include the raw PDF bytes instead of a URL. This is useful if you need to upload to your own S3 bucket or attach directly to an email.

Step 4: Email the Invoice

With the PDF URL in hand, sending the invoice email is straightforward. Resend provides a clean API for transactional email with attachment support.

import { Resend } from "resend";

const resend = new Resend(process.env.RESEND_API_KEY!);

async function emailInvoice(
  customerEmail: string,
  pdfUrl: string,
  data: InvoiceTemplateData
) {
  await resend.emails.send({
    from: `${data.company_name} <billing@${process.env.EMAIL_DOMAIN}>`,
    to: customerEmail,
    subject: `Invoice ${data.invoice_number} - ${data.amount_due}`,
    html: `
      <p>Hi ${data.customer_name},</p>
      <p>Thank you for your payment of <strong>${data.amount_due}</strong>.</p>
      <p>Your invoice is ready:
        <a href="${pdfUrl}">Download Invoice ${data.invoice_number}</a>
      </p>
      <p>Best regards,<br>${data.company_name}</p>
    `,
  });

  console.log(`Invoice emailed to ${customerEmail}`);
}

This approach sends a link to the hosted PDF. The customer clicks the link and downloads the file. For many use cases, this is preferable -- the email stays small and the PDF is always accessible.

If your customers expect the PDF as an email attachment, use the base64 output option and attach it directly:

async function emailInvoiceWithAttachment(
  customerEmail: string,
  data: InvoiceTemplateData
) {
  const pdf = await df.fromTemplate({
    template: process.env.INVOICE_TEMPLATE_ID!,
    data,
    output: "base64",
  });

  await resend.emails.send({
    from: `${data.company_name} <billing@${process.env.EMAIL_DOMAIN}>`,
    to: customerEmail,
    subject: `Invoice ${data.invoice_number} - ${data.amount_due}`,
    html: `
      <p>Hi ${data.customer_name},</p>
      <p>Thank you for your payment. Your invoice is attached.</p>
      <p>Best regards,<br>${data.company_name}</p>
    `,
    attachments: [
      {
        filename: `invoice-${data.invoice_number}.pdf`,
        content: pdf.url, // base64 string when output is 'base64'
      },
    ],
  });
}

Choose whichever approach fits your customers. The hosted URL is simpler and keeps email deliverability high. The attachment approach gives customers the file immediately without clicking a link.

Step 5: Batch Invoices for Monthly Billing

If you run a subscription business, you might need to generate dozens or hundreds of invoices at the end of each billing cycle. Generating them one by one would be slow and wasteful. DocuForge's batch endpoint handles this efficiently -- you submit all invoices in a single request, and they are processed concurrently on DocuForge's infrastructure.

async function generateMonthlyInvoices(
  invoices: InvoiceTemplateData[]
) {
  const batchItems = invoices.map((data) => ({
    template: process.env.INVOICE_TEMPLATE_ID!,
    data,
    options: {
      format: "A4" as const,
      margin: { top: "20mm", right: "20mm", bottom: "30mm", left: "20mm" },
      printBackground: true,
      footer: `
        <div style="width: 100%; text-align: center; font-size: 10px; color: #9ca3af;">
          Page {{pageNumber}} of {{totalPages}}
        </div>
      `,
    },
  }));

  const batch = await df.batch({
    items: batchItems,
    webhook: "https://your-app.com/api/webhooks/docuforge-batch",
  });

  console.log(`Batch submitted: ${batch.batch_id}`);
  console.log(`Total invoices: ${batch.total}`);
  console.log(`Status: ${batch.status}`); // "queued"

  // Each item gets a generation ID for tracking
  for (const gen of batch.generations) {
    console.log(`  Invoice #${gen.index}: ${gen.id}`);
  }

  return batch;
}

The batch endpoint returns HTTP 202 with a batch_id and the status "queued". Each item in the batch gets its own generation ID that you can use to track progress.

There are two ways to know when the batch is complete. The recommended approach is the webhook callback -- DocuForge will POST to your webhook URL when all items are finished. Alternatively, you can poll individual generations:

async function pollGeneration(generationId: string): Promise<string> {
  const maxAttempts = 30;
  const delayMs = 2000;

  for (let i = 0; i < maxAttempts; i++) {
    const generation = await df.getGeneration(generationId);

    if (generation.status === "completed") {
      return generation.url;
    }

    if (generation.status === "failed") {
      throw new Error(`Generation ${generationId} failed`);
    }

    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }

  throw new Error(`Generation ${generationId} timed out`);
}

For production use, the webhook approach is strongly preferred. Polling works for development and debugging but wastes API calls at scale.

Complete Code

Here is the consolidated code for the entire invoice system. This is a single Next.js API route file that handles the Stripe webhook, generates the PDF, and sends the email:

// app/api/webhooks/stripe/route.ts
import { NextRequest, NextResponse } from "next/server";
import Stripe from "stripe";
import DocuForge from "docuforge";
import { Resend } from "resend";

// --- Clients ---

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2024-12-18.acacia",
});

const df = new DocuForge(process.env.DOCUFORGE_API_KEY!);
const resend = new Resend(process.env.RESEND_API_KEY!);

// --- Types ---

interface InvoiceTemplateData {
  company_name: string;
  company_address: string;
  company_email: string;
  customer_name: string;
  customer_email: string;
  customer_address?: string;
  invoice_number: string;
  date: string;
  line_items: {
    description: string;
    quantity: number;
    unit_price: string;
    amount: string;
  }[];
  subtotal: string;
  tax?: string;
  amount_due: string;
}

// --- Helpers ---

function formatCents(cents: number, currency: string): string {
  return new Intl.NumberFormat("en-US", {
    style: "currency",
    currency: currency.toUpperCase(),
  }).format(cents / 100);
}

function mapStripeInvoice(invoice: Stripe.Invoice): InvoiceTemplateData {
  const currency = invoice.currency;

  const lineItems = (invoice.lines?.data ?? []).map((line) => ({
    description: line.description ?? "Service",
    quantity: line.quantity ?? 1,
    unit_price: formatCents(
      line.unit_amount_excluding_tax
        ? parseInt(line.unit_amount_excluding_tax)
        : line.amount / (line.quantity ?? 1),
      currency
    ),
    amount: formatCents(line.amount, currency),
  }));

  return {
    company_name: process.env.COMPANY_NAME ?? "Your Company",
    company_address: process.env.COMPANY_ADDRESS ?? "",
    company_email: process.env.COMPANY_EMAIL ?? "",
    customer_name: invoice.customer_name ?? "Customer",
    customer_email: invoice.customer_email ?? "",
    customer_address: invoice.customer_address?.line1
      ? [
          invoice.customer_address.line1,
          invoice.customer_address.city,
          invoice.customer_address.state,
          invoice.customer_address.postal_code,
        ]
          .filter(Boolean)
          .join(", ")
      : undefined,
    invoice_number: invoice.number ?? invoice.id,
    date: new Date(
      (invoice.status_transitions?.paid_at ?? Date.now() / 1000) * 1000
    ).toLocaleDateString("en-US", {
      year: "numeric",
      month: "long",
      day: "numeric",
    }),
    line_items: lineItems,
    subtotal: formatCents(invoice.subtotal, currency),
    tax: invoice.tax ? formatCents(invoice.tax, currency) : undefined,
    amount_due: formatCents(invoice.amount_paid, currency),
  };
}

// --- PDF Generation ---

async function generateInvoicePdf(
  data: InvoiceTemplateData
): Promise<string> {
  const pdf = await df.fromTemplate({
    template: process.env.INVOICE_TEMPLATE_ID!,
    data,
    options: {
      format: "A4",
      margin: { top: "20mm", right: "20mm", bottom: "30mm", left: "20mm" },
      printBackground: true,
      footer: `
        <div style="width: 100%; text-align: center; font-size: 10px; color: #9ca3af;">
          Page {{pageNumber}} of {{totalPages}}
        </div>
      `,
    },
  });

  console.log(
    `Invoice PDF generated: ${pdf.id} (${pdf.pages} pages, ${pdf.file_size} bytes, ${pdf.generation_time_ms}ms)`
  );

  return pdf.url;
}

// --- Email ---

async function emailInvoice(
  customerEmail: string,
  pdfUrl: string,
  data: InvoiceTemplateData
) {
  await resend.emails.send({
    from: `${data.company_name} <billing@${process.env.EMAIL_DOMAIN}>`,
    to: customerEmail,
    subject: `Invoice ${data.invoice_number} - ${data.amount_due}`,
    html: `
      <p>Hi ${data.customer_name},</p>
      <p>Thank you for your payment of <strong>${data.amount_due}</strong>.</p>
      <p>Your invoice is ready:
        <a href="${pdfUrl}">Download Invoice ${data.invoice_number}</a>
      </p>
      <p>Best regards,<br>${data.company_name}</p>
    `,
  });

  console.log(`Invoice emailed to ${customerEmail}`);
}

// --- Webhook Handler ---

export async function POST(req: NextRequest) {
  const body = await req.text();
  const signature = req.headers.get("stripe-signature");

  if (!signature) {
    return NextResponse.json(
      { error: "Missing stripe-signature header" },
      { status: 400 }
    );
  }

  let event: Stripe.Event;

  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err) {
    console.error("Webhook signature verification failed:", err);
    return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
  }

  if (event.type === "invoice.payment_succeeded") {
    const invoice = event.data.object as Stripe.Invoice;

    try {
      const data = mapStripeInvoice(invoice);
      const pdfUrl = await generateInvoicePdf(data);

      if (invoice.customer_email) {
        await emailInvoice(invoice.customer_email, pdfUrl, data);
      }
    } catch (err) {
      console.error("Failed to process invoice:", err);
      // Return 500 so Stripe retries the webhook
      return NextResponse.json(
        { error: "Processing failed" },
        { status: 500 }
      );
    }
  }

  return NextResponse.json({ received: true });
}

Environment variables -- add these to your .env.local:

# Stripe
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

# DocuForge
DOCUFORGE_API_KEY=df_live_...
INVOICE_TEMPLATE_ID=tmpl_...

# Resend
RESEND_API_KEY=re_...
EMAIL_DOMAIN=yourdomain.com

# Company info (used in invoice template)
COMPANY_NAME="Acme Inc"
COMPANY_ADDRESS="123 Main St, San Francisco, CA 94102"
COMPANY_EMAIL="billing@acme.com"

A few production considerations worth noting. First, return 500 from the webhook if PDF generation or email fails -- Stripe will retry the event with exponential backoff for up to 3 days. Second, add idempotency checks by storing processed Stripe event IDs so you do not generate duplicate invoices on retries. Third, consider generating the PDF asynchronously with a background job if webhook response time is a concern -- Stripe expects a response within 20 seconds.

Going Further

This tutorial covered the core flow: Stripe payment to PDF invoice to customer email. There are several directions you can take it from here.

For reporting, look at our guide on generating Supabase reports with DocuForge -- the same template and batch patterns apply to monthly financial summaries.

If you want more control over page layout -- custom headers per page, landscape tables, or page break control -- the page layout and headers guide covers all the options available in the PDFOptions object.

For teams building a full SaaS billing portal, the Next.js integration guide shows how to add a customer-facing invoice history page with on-demand PDF regeneration.

Django PDF Generation Made Simple

Fred T — Wed, 18 Mar 2026 17:00:00 +0000

Introduction

Django developers who need to generate PDFs have traditionally reached for libraries like ReportLab, WeasyPrint, or xhtml2pdf. Each has its own quirks: ReportLab forces you to build documents programmatically rather than from HTML, WeasyPrint requires system-level dependencies that complicate deployment, and xhtml2pdf struggles with modern CSS. All of them run rendering in-process, consuming server resources and introducing maintenance burden.

DocuForge eliminates this complexity. One pip install, one API call, and you get back a pixel-perfect PDF rendered by a headless Chromium instance managed entirely by the DocuForge service. The Python SDK is synchronous and fits naturally into Django's request-response cycle.

In this tutorial you will build Django views that cover the most common PDF workflows: converting raw HTML, generating invoices from templates with file downloads, integrating with Django REST Framework, building reusable class-based views, and adding PDF export actions to the Django admin.

Step 1: Install and Configure

Start by installing the DocuForge Python SDK alongside your Django project dependencies.

pip install docuforge

Add your API key to your Django settings. You can grab one from the DocuForge dashboard. Never hard-code API keys in source files -- pull them from environment variables.

# settings.py
import os

DOCUFORGE_API_KEY = os.environ["DOCUFORGE_API_KEY"]

Create a small utility module so you do not repeat the client initialization across views.

# pdf/utils.py
from django.conf import settings
from docuforge import DocuForge


def get_docuforge_client():
    return DocuForge(api_key=settings.DOCUFORGE_API_KEY)

This function returns a client instance you can use as a context manager in any view. Keeping it in one place means you only need to change configuration once if your setup evolves.

Step 2: Basic PDF Generation View

The simplest integration is a function-based view that accepts HTML in a POST request and returns the generated PDF metadata as JSON.

# pdf/views.py
import json
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
from docuforge import (
    AuthenticationError,
    RateLimitError,
    ValidationError,
    DocuForgeError,
)
from .utils import get_docuforge_client


@csrf_exempt
@require_POST
def generate_pdf(request):
    try:
        body = json.loads(request.body)
    except json.JSONDecodeError:
        return JsonResponse({"error": "Invalid JSON"}, status=400)

    html = body.get("html")
    if not html:
        return JsonResponse({"error": "html field is required"}, status=400)

    try:
        with get_docuforge_client() as df:
            pdf = df.generate(
                html=html,
                options={
                    "format": body.get("format", "A4"),
                    "margin": body.get("margin", "20mm"),
                    "printBackground": True,
                },
            )

        return JsonResponse({
            "id": pdf.id,
            "url": pdf.url,
            "status": pdf.status,
            "pages": pdf.pages,
            "file_size": pdf.file_size,
            "generation_time_ms": pdf.generation_time_ms,
        })

    except AuthenticationError:
        return JsonResponse({"error": "Invalid API key"}, status=401)
    except RateLimitError:
        return JsonResponse({"error": "Rate limit exceeded"}, status=429)
    except ValidationError as e:
        return JsonResponse({"error": f"Validation failed: {e}"}, status=400)
    except DocuForgeError as e:
        return JsonResponse({"error": f"PDF generation failed: {e}"}, status=502)

Wire it up in your URL configuration:

# pdf/urls.py
from django.urls import path
from . import views

urlpatterns = [
    path("generate/", views.generate_pdf, name="generate_pdf"),
]

The @csrf_exempt decorator is necessary here because this endpoint receives JSON from API clients rather than Django form submissions. The @require_POST decorator rejects anything that is not a POST request. The DocuForge error hierarchy maps cleanly to HTTP status codes: AuthenticationError to 401, RateLimitError to 429, ValidationError to 400, and the base DocuForgeError to 502 for upstream failures.

Step 3: Template-Based Invoice Download

Most production use cases involve templates rather than raw HTML. This view fetches an invoice from your database, passes its data to a DocuForge template, and returns the PDF as a direct file download.

Assume you have an Invoice model:

# invoices/models.py
from django.db import models


class Invoice(models.Model):
    number = models.CharField(max_length=50, unique=True)
    customer_name = models.CharField(max_length=200)
    total = models.DecimalField(max_digits=10, decimal_places=2)
    created_at = models.DateTimeField(auto_now_add=True)


class InvoiceItem(models.Model):
    invoice = models.ForeignKey(Invoice, on_delete=models.CASCADE, related_name="items")
    description = models.CharField(max_length=300)
    amount = models.DecimalField(max_digits=10, decimal_places=2)

Now build the download view:

# invoices/views.py
import base64
from django.http import HttpResponse, Http404
from django.conf import settings
from docuforge import DocuForge

INVOICE_TEMPLATE_ID = "tmpl_your_template_id"


def download_invoice_pdf(request, invoice_id):
    try:
        invoice = Invoice.objects.prefetch_related("items").get(pk=invoice_id)
    except Invoice.DoesNotExist:
        raise Http404("Invoice not found")

    template_data = {
        "invoice_number": invoice.number,
        "customer_name": invoice.customer_name,
        "items": [
            {"description": item.description, "amount": str(item.amount)}
            for item in invoice.items.all()
        ],
        "total": str(invoice.total),
    }

    with DocuForge(api_key=settings.DOCUFORGE_API_KEY) as df:
        pdf = df.from_template(
            template=INVOICE_TEMPLATE_ID,
            data=template_data,
            options={"format": "A4", "margin": "20mm"},
            output="base64",
        )

    pdf_bytes = base64.b64decode(pdf.data)

    response = HttpResponse(pdf_bytes, content_type="application/pdf")
    response["Content-Disposition"] = f'attachment; filename="invoice-{invoice.number}.pdf"'
    response["Content-Length"] = len(pdf_bytes)
    return response

Add the URL pattern:

# invoices/urls.py
from django.urls import path
from . import views

urlpatterns = [
    path("<int:invoice_id>/pdf/", views.download_invoice_pdf, name="invoice_pdf"),
]

Setting output="base64" tells DocuForge to return the PDF content as a base64-encoded string instead of a hosted URL. You decode it with the standard library, wrap it in an HttpResponse with content_type="application/pdf", and set the Content-Disposition header to trigger a browser download. The filename includes the invoice number so users can identify the file after saving.

Step 4: Django REST Framework Integration

If your project uses Django REST Framework, you can build a more structured integration with serializers and viewsets.

# pdf/serializers.py
from rest_framework import serializers


class PDFGenerateSerializer(serializers.Serializer):
    html = serializers.CharField(required=True)
    format = serializers.ChoiceField(
        choices=["A4", "Letter", "Legal", "A3"],
        default="A4",
    )
    margin = serializers.CharField(default="20mm")
    orientation = serializers.ChoiceField(
        choices=["portrait", "landscape"],
        default="portrait",
    )

Now create a viewset with a custom action:

# pdf/api_views.py
from rest_framework import status, viewsets
from rest_framework.decorators import action
from rest_framework.response import Response
from django.conf import settings
from docuforge import (
    DocuForge,
    AuthenticationError,
    RateLimitError,
    ValidationError,
    DocuForgeError,
)
from .serializers import PDFGenerateSerializer


class PDFViewSet(viewsets.ViewSet):

    @action(detail=False, methods=["post"])
    def generate(self, request):
        serializer = PDFGenerateSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        data = serializer.validated_data

        try:
            with DocuForge(api_key=settings.DOCUFORGE_API_KEY) as df:
                pdf = df.generate(
                    html=data["html"],
                    options={
                        "format": data["format"],
                        "margin": data["margin"],
                        "orientation": data["orientation"],
                        "printBackground": True,
                    },
                )

            return Response({
                "id": pdf.id,
                "url": pdf.url,
                "status": pdf.status,
                "pages": pdf.pages,
                "file_size": pdf.file_size,
                "generation_time_ms": pdf.generation_time_ms,
            })

        except AuthenticationError:
            return Response(
                {"error": "Invalid API key"},
                status=status.HTTP_401_UNAUTHORIZED,
            )
        except RateLimitError:
            return Response(
                {"error": "Rate limit exceeded"},
                status=status.HTTP_429_TOO_MANY_REQUESTS,
            )
        except ValidationError as e:
            return Response(
                {"error": f"Validation failed: {e}"},
                status=status.HTTP_400_BAD_REQUEST,
            )
        except DocuForgeError as e:
            return Response(
                {"error": f"PDF generation failed: {e}"},
                status=status.HTTP_502_BAD_GATEWAY,
            )

# pdf/urls.py
from rest_framework.routers import DefaultRouter
from .api_views import PDFViewSet

router = DefaultRouter()
router.register(r"pdf", PDFViewSet, basename="pdf")

urlpatterns = router.urls

The serializer handles input validation and provides clear error messages before any API call is made. DRF's is_valid(raise_exception=True) returns a 400 response automatically if the data does not match the schema. The DocuForge error classes map to DRF's status constants, keeping the response format consistent with the rest of your API.

Step 5: Class-Based View Approach

For projects that follow Django's class-based view conventions, you can build a reusable base view and a mixin pattern.

# pdf/cbv.py
import base64
from django.http import HttpResponse, JsonResponse
from django.views import View
from django.conf import settings
from docuforge import DocuForge, DocuForgeError


class PDFGenerationView(View):
    """Base view for PDF generation. Subclass and override get_html()."""

    pdf_options = {"format": "A4", "margin": "20mm", "printBackground": True}
    filename = "document.pdf"

    def get_html(self, request, **kwargs):
        raise NotImplementedError("Subclasses must implement get_html()")

    def get(self, request, **kwargs):
        html = self.get_html(request, **kwargs)

        try:
            with DocuForge(api_key=settings.DOCUFORGE_API_KEY) as df:
                pdf = df.generate(
                    html=html,
                    options=self.pdf_options,
                    output="base64",
                )
        except DocuForgeError as e:
            return JsonResponse({"error": str(e)}, status=502)

        pdf_bytes = base64.b64decode(pdf.data)
        response = HttpResponse(pdf_bytes, content_type="application/pdf")
        response["Content-Disposition"] = f'attachment; filename="{self.filename}"'
        return response

You can also define a mixin that adds PDF export capability to any existing detail view:

# pdf/mixins.py
import base64
from django.http import HttpResponse
from django.conf import settings
from docuforge import DocuForge
from django.template.loader import render_to_string


class PDFExportMixin:
    """Add PDF export to any detail view. Set pdf_template_name and pdf_filename."""

    pdf_template_name = None
    pdf_filename = "export.pdf"
    pdf_options = {"format": "A4", "margin": "20mm"}

    def render_pdf(self, request, context):
        html = render_to_string(self.pdf_template_name, context, request=request)

        with DocuForge(api_key=settings.DOCUFORGE_API_KEY) as df:
            pdf = df.generate(html=html, options=self.pdf_options, output="base64")

        pdf_bytes = base64.b64decode(pdf.data)
        response = HttpResponse(pdf_bytes, content_type="application/pdf")
        response["Content-Disposition"] = f'attachment; filename="{self.pdf_filename}"'
        return response

Using the mixin, any view that already builds a context dictionary can add a PDF export route with minimal code. The render_to_string call renders a Django template to HTML, which DocuForge then converts to PDF. This lets you reuse your existing Django templates -- the same Jinja-style markup you already write for web pages can produce PDFs with no modifications.

Step 6: Admin Integration

Django's admin interface supports custom actions on list views. Adding a "Download PDF" action lets staff members generate PDFs for selected records directly from the admin.

# invoices/admin.py
import base64
from django.contrib import admin
from django.http import HttpResponse
from django.conf import settings
from docuforge import DocuForge
from .models import Invoice, InvoiceItem


class InvoiceItemInline(admin.TabularInline):
    model = InvoiceItem
    extra = 0


@admin.register(Invoice)
class InvoiceAdmin(admin.ModelAdmin):
    list_display = ("number", "customer_name", "total", "created_at")
    inlines = [InvoiceItemInline]
    actions = ["download_pdfs"]

    @admin.action(description="Download PDF for selected invoices")
    def download_pdfs(self, request, queryset):
        items = []
        for invoice in queryset.prefetch_related("items"):
            items.append({
                "html": self._build_invoice_html(invoice),
                "options": {"format": "A4", "margin": "20mm"},
            })

        with DocuForge(api_key=settings.DOCUFORGE_API_KEY) as df:
            if len(items) == 1:
                pdf = df.generate(
                    html=items[0]["html"],
                    options=items[0]["options"],
                    output="base64",
                )
                pdf_bytes = base64.b64decode(pdf.data)
                filename = f"invoice-{queryset.first().number}.pdf"
            else:
                result = df.batch(items)
                self.message_user(
                    request,
                    f"Batch job submitted for {len(items)} invoices. "
                    f"Results will be available at the URLs returned by the API.",
                )
                return

        response = HttpResponse(pdf_bytes, content_type="application/pdf")
        response["Content-Disposition"] = f'attachment; filename="{filename}"'
        return response

    def _build_invoice_html(self, invoice):
        items_html = "".join(
            f"<tr><td>{item.description}</td>"
            f"<td style='text-align:right;'>${item.amount}</td></tr>"
            for item in invoice.items.all()
        )
        return f"""
        <html>
        <body style="font-family: sans-serif; padding: 40px;">
            <h1>Invoice #{invoice.number}</h1>
            <p>Bill to: {invoice.customer_name}</p>
            <table style="width:100%; border-collapse:collapse;">
                <tr style="border-bottom:1px solid #ccc;">
                    <th style="text-align:left;">Item</th>
                    <th style="text-align:right;">Amount</th>
                </tr>
                {items_html}
            </table>
            <h2 style="text-align:right; margin-top:20px;">Total: ${invoice.total}</h2>
        </body>
        </html>
        """

When a single invoice is selected, the action generates the PDF immediately and returns it as a file download. When multiple invoices are selected, it submits a batch job using df.batch(), which queues the work asynchronously and returns immediately. The batch approach is the right choice for bulk operations because it avoids tying up the request while multiple PDFs render sequentially.

The @admin.action decorator (available in Django 3.2 and later) registers the method as a list action. Staff members select invoices using the checkboxes in the admin list view, choose "Download PDF for selected invoices" from the action dropdown, and click "Go."

Going Further

This tutorial covered the core patterns for integrating DocuForge into a Django application -- function-based views, template-based downloads, DRF integration, class-based views, and admin actions. From here you can explore several directions:

FastAPI integration -- If parts of your system use FastAPI, the SDK works identically. See our FastAPI tutorial for async patterns and Pydantic model examples.
Comparing rendering approaches -- If you are evaluating DocuForge against Puppeteer or WeasyPrint, the DocuForge vs Puppeteer article breaks down the trade-offs in performance, accuracy, and operational overhead.
Page layout control -- Our page layout guide covers headers, footers, page numbers, and multi-column layouts in detail.
Batch processing -- The df.batch() method is ideal for scheduled jobs like monthly invoice runs. Pair it with Django management commands or Celery tasks for fully automated PDF pipelines.

DocuForge vs Puppeteer: Why I Switched

Fred T — Wed, 18 Mar 2026 13:00:00 +0000

DocuForge vs Puppeteer: Why I Switched

I spent three days getting Puppeteer to reliably generate invoices in production. Three days of debugging Chromium crashes inside Docker, wrestling with memory limits, and writing retry logic that should not have been my responsibility. Then I found DocuForge and replaced the entire setup in about ten minutes.

This is not a theoretical comparison post. I am going to walk through the exact Puppeteer code I was running, the problems I hit, and how the same workflow looks with DocuForge. I will be honest about when Puppeteer still makes sense. But for my use case -- a SaaS that generates invoices, receipts, and shipping labels at moderate scale -- the switch was one of the best infrastructure decisions I made last year.

If you are currently running Puppeteer or Playwright in production for PDF generation, or if you are about to set it up for the first time, this post will save you time. You will see the real tradeoffs, not a marketing page.

Let me start with what I was running before.

The Puppeteer Setup I Was Running

My application is a Node.js API that generates invoices after successful payments. Customers expect a PDF link in their email within a few seconds of checkout. Here is a simplified version of what the Puppeteer code looked like:

import puppeteer from "puppeteer";
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({ region: "us-east-1" });

async function generateInvoicePDF(html: string, invoiceId: string) {
  const browser = await puppeteer.launch({
    headless: "new",
    args: [
      "--no-sandbox",
      "--disable-setuid-sandbox",
      "--disable-dev-shm-usage",
      "--disable-gpu",
    ],
  });

  try {
    const page = await browser.newPage();
    await page.setContent(html, { waitUntil: "networkidle0" });

    const pdfBuffer = await page.pdf({
      format: "A4",
      printBackground: true,
      margin: { top: "20mm", bottom: "20mm", left: "15mm", right: "15mm" },
      displayHeaderFooter: true,
      headerTemplate: `<div style="font-size:10px; width:100%; text-align:center;">Invoice ${invoiceId}</div>`,
      footerTemplate: `<div style="font-size:10px; width:100%; text-align:center;">
        Page <span class="pageNumber"></span> of <span class="totalPages"></span>
      </div>`,
    });

    await s3.send(
      new PutObjectCommand({
        Bucket: "my-invoices",
        Key: `invoices/${invoiceId}.pdf`,
        Body: pdfBuffer,
        ContentType: "application/pdf",
      })
    );

    return `https://my-invoices.s3.amazonaws.com/invoices/${invoiceId}.pdf`;
  } finally {
    await browser.close();
  }
}

That is roughly 40 lines just to generate one PDF and upload it. But the code was only half the problem. The Dockerfile was where things got ugly:

FROM node:20-slim

RUN apt-get update && apt-get install -y \
    chromium \
    fonts-liberation \
    libasound2 \
    libatk-bridge2.0-0 \
    libatk1.0-0 \
    libcups2 \
    libdbus-1-3 \
    libdrm2 \
    libgbm1 \
    libgtk-3-0 \
    libnspr4 \
    libnss3 \
    libxcomposite1 \
    libxdamage1 \
    libxrandr2 \
    --no-install-recommends \
    && rm -rf /var/lib/apt/lists/*

ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

WORKDIR /app
COPY . .
RUN npm ci --production
CMD ["node", "server.js"]

This Dockerfile alone added about 400MB to the image. Every CI build took noticeably longer. Every deploy pushed a larger image. And every time Chromium updated, something broke.

The code worked on my machine. Getting it to work reliably in production was a different story.

Problem 1: Memory Leaks and Crashes

The first serious issue was memory. Every call to puppeteer.launch() spins up a full Chromium process. On a 512MB container, that means you can handle maybe two or three concurrent requests before the OOM killer steps in.

I started seeing this in production within the first week. A burst of five invoice requests would arrive at once -- a common pattern after a batch of orders -- and the container would restart. Customers got 502 errors. The invoices never generated. Support tickets followed.

The obvious fix is to keep a browser instance alive and reuse it. So I built a simple browser pool:

let browser: Browser | null = null;
let useCount = 0;

async function getBrowser() {
  if (!browser || useCount >= 50) {
    if (browser) await browser.close();
    browser = await puppeteer.launch({ headless: "new", args: ["--no-sandbox"] });
    useCount = 0;
  }
  useCount++;
  return browser;
}

This helped, but it introduced new problems. If the browser crashed mid-render, the pool returned a dead instance. I had to add health checks, crash detection, and automatic recovery. What started as 40 lines of PDF code was now 200 lines of browser lifecycle management.

DocuForge handles all of this internally. Its browser pool keeps 2-3 Chromium instances alive, assigns requests via round-robin, and recycles each instance after 100 uses. I did not know that when I switched -- I just knew my PDFs stopped failing. Later, reading their architecture docs, I understood why. The pool management that took me a week to get right was a solved problem from day one.

Problem 2: Headers, Footers, and Page Breaks

Puppeteer's displayHeaderFooter option sounds great until you actually use it. The header and footer templates run in a completely separate rendering context from the main page content. That means:

You cannot use your page's CSS. The headers and footers have their own isolated styles.
Font loading is unreliable. Custom fonts that render perfectly in the body often fail in headers and footers.
The positioning is tricky. You need to manually adjust margins to prevent the header from overlapping the body content, and the relationship between margin in the PDF options and the actual header/footer height is not intuitive.

CSS page breaks were another frustration. I had multi-page invoices where a line item table needed to break cleanly across pages. In theory, break-inside: avoid on table rows should handle this. In practice, Chromium's print rendering engine has its own opinions. I spent an afternoon experimenting with combinations of page-break-before, page-break-after, break-inside, and wrapper divs before finding a combination that worked consistently.

DocuForge still uses Chromium under the hood, so the rendering engine is the same. But their header and footer handling is cleaner. You pass header and footer as HTML strings in the options, and they support {{pageNumber}} and {{totalPages}} as interpolation variables:

const pdf = await df.generate({
  html: invoiceHtml,
  options: {
    format: "A4",
    header: `<div style="font-size:10px; text-align:center; width:100%;">Invoice #1234</div>`,
    footer: `<div style="font-size:10px; text-align:center; width:100%;">
      Page {{pageNumber}} of {{totalPages}}
    </div>`,
  },
});

The {{pageNumber}} and {{totalPages}} variables are interpolated before rendering, which means they work reliably regardless of how Chromium decides to handle the print context. It is a small detail that saves real debugging time.

Problem 3: Multi-Language SDKs

Six months into production, our Python team needed to generate PDF reports from a Django analytics service. The invoicing logic lived in our Node.js API, but the analytics reports were a completely separate codebase in Python.

We had two options. First, duplicate the entire Puppeteer setup in Python using Pyppeteer or Playwright for Python. That meant another Dockerfile with Chromium, another browser pool, another set of memory issues to debug. Second, build an internal PDF generation microservice that both the Node.js and Python codebases could call over HTTP.

We went with option two, and it worked, but we were now maintaining a standalone service just to wrap Puppeteer behind an HTTP API. We had accidentally built a worse version of what DocuForge already provides.

With DocuForge, the Python team just installed the SDK:

pip install docuforge

from docuforge import DocuForge

df = DocuForge("df_live_your_api_key_here")
result = df.generate(html=report_html, options={"format": "A4"})
print(result.url)

Same API, same response shape, no infrastructure. They also have SDKs for Go and Ruby, which means any future service we build can generate PDFs without standing up its own Chromium instance.

The Switch: DocuForge in 10 Minutes

Let me show you the before and after. Here is the Puppeteer version again, condensed to its core:

// Puppeteer: ~40 lines, plus Dockerfile, plus browser pool, plus S3 upload
import puppeteer from "puppeteer";

const browser = await puppeteer.launch({ headless: "new", args: ["--no-sandbox"] });
const page = await browser.newPage();
await page.setContent(invoiceHtml, { waitUntil: "networkidle0" });
const pdfBuffer = await page.pdf({
  format: "A4",
  printBackground: true,
  margin: { top: "20mm", bottom: "20mm", left: "15mm", right: "15mm" },
});
await browser.close();

// Then manually upload to S3...
// Then manage the browser pool...
// Then handle crashes, retries, cleanup...

Here is the DocuForge version:

// DocuForge: 6 lines, no infrastructure
import DocuForge from "docuforge";

const df = new DocuForge(process.env.DOCUFORGE_API_KEY!);

const pdf = await df.generate({
  html: invoiceHtml,
  options: {
    format: "A4",
    printBackground: true,
    margin: { top: "20mm", bottom: "20mm", left: "15mm", right: "15mm" },
  },
});

console.log(pdf.url); // hosted URL, ready to use

The response object gives you everything you need: id, status, url, pages, file_size, and generation_time_ms. The PDF is stored automatically -- DocuForge supports local storage, Cloudflare R2, AWS S3, and Google Cloud Storage -- so there is no manual upload step.

For templated documents, the difference is even starker. Instead of building HTML strings with string interpolation (or setting up a template engine yourself), DocuForge has built-in Handlebars support:

const pdf = await df.fromTemplate({
  template: "tmpl_invoice_standard",
  data: {
    customerName: "Acme Corp",
    items: [
      { name: "Widget Pro", quantity: 3, price: 29.99 },
      { name: "Gadget Plus", quantity: 1, price: 49.99 },
    ],
    total: 139.96,
  },
  options: { format: "A4" },
});

Templates support {{variable}}, {{#each items}}, {{#if condition}}, and the full Handlebars syntax. They are stored server-side with version history, so you can update an invoice layout without redeploying your application.

The migration took about ten minutes. I removed the Puppeteer dependency, deleted the browser pool code, deleted the S3 upload logic, removed Chromium from the Dockerfile, and installed the docuforge npm package. The Docker image dropped from 800MB to 200MB.

Feature Comparison Table

Here is a side-by-side comparison of what you get with each approach:

Feature	Puppeteer (Self-Hosted)	DocuForge
Setup time	Hours to days (Docker, Chromium, pool)	5 minutes (npm install + API key)
Infrastructure	Your servers, your Chromium, your problem	Managed service, nothing to host
Browser management	Manual pool, crash recovery, recycling	Automatic pool (2-3 instances, round-robin, 100-use recycling)
SDKs	JavaScript/TypeScript only	TypeScript, Python, Go, Ruby
Template engine	BYO (Handlebars, EJS, etc.)	Built-in Handlebars with version history
Batch generation	Manual queue implementation	Built-in BullMQ queue with retries
PDF storage	Manual S3/R2/GCS upload	Built-in (local, R2, S3, GCS)
Headers/footers	Limited, isolated rendering context	HTML with `{{pageNumber}}` / `{{totalPages}}`
React-to-PDF	Not supported natively	`fromReact()` with JSX/TSX transpilation
Rate limiting	Manual implementation	Built-in, plan-based
Usage tracking	Manual logging	Built-in dashboard with daily/monthly stats
Cost model	Server costs + engineering time	API pricing based on usage
Docker image size	+400MB for Chromium	No Chromium needed in your image

The features that saved me the most time were the built-in storage and the browser pool. Those two things alone represented about 300 lines of code I no longer needed to maintain.

Performance Comparison

I ran both setups against the same invoice HTML to get a rough comparison. These numbers are from a real workload, not a synthetic benchmark, so take them as directional rather than definitive.

Puppeteer (self-hosted, 1GB container):

Cold start (first PDF after deploy): 3-5 seconds
Warm (browser already running): 1-3 seconds
Concurrent requests: 2-3 before degradation on a 1GB container
Memory: scales linearly with concurrency; each page adds ~50-80MB

DocuForge API:

Consistent generation time: 1-2 seconds
No cold start penalty (pool is always warm)
Concurrent requests: handled by the service; rate limits depend on plan (10-500 req/s)
Memory: zero on your infrastructure

The consistency was what mattered most to me. With Puppeteer, the p50 latency was fine, but the p99 was unpredictable. A garbage collection pause or a page with heavy CSS could push a single render to 5+ seconds. With DocuForge, the generation times clustered tightly around 1-2 seconds because their pool is purpose-built for this workload.

For batch generation, the difference was even more pronounced. Generating 50 invoices with Puppeteer meant either sequential processing (slow) or a concurrency limit of 2-3 (still slow, and risky). DocuForge's batch endpoint accepts the full set and processes them through a BullMQ queue with concurrency of 5, retries, and exponential backoff. I just fire the request and poll for completion.

When Puppeteer Still Makes Sense

I want to be honest here. Puppeteer is not a bad tool. It is a bad tool for PDF-only workloads in production. There are legitimate reasons to keep it:

Full browser automation. If you need screenshots, scraping, end-to-end testing, or any interaction beyond "render HTML to PDF," Puppeteer is the right choice. DocuForge is a PDF API, not a general-purpose browser automation tool.

Strict data residency requirements. If your compliance rules require that document data never leaves your infrastructure, a self-hosted solution is necessary. DocuForge does offer a self-hosted Docker deployment, but you should evaluate whether that meets your specific compliance needs.

You are already operating at massive scale. If you have already invested in a robust browser pool with health checks, auto-scaling, and monitoring, and it is working well, the migration cost may not be worth it. The argument for DocuForge is strongest when you are setting up PDF generation for the first time or when your current setup is causing pain.

Cost sensitivity at very high volume. If you are generating hundreds of thousands of PDFs per month, the math changes. At that scale, a dedicated Puppeteer cluster on cheap compute might cost less than API pricing. Run the numbers for your specific volume.

For everyone else -- and that includes most teams generating PDFs in production -- the engineering time saved by not managing Chromium infrastructure is worth far more than the API cost.

Conclusion

Switching from Puppeteer to DocuForge was not a dramatic, everything-changed moment. It was more like removing a constant low-grade headache. I stopped worrying about browser crashes. I stopped debugging Docker memory limits. I stopped maintaining a browser pool. I just called an API and got a PDF back.

If you are starting a new project that needs PDF generation, I would recommend trying DocuForge first. You can always fall back to Puppeteer if you hit a limitation, but chances are you will not need to.

To get started, check out these tutorials:

You can grab an API key from the dashboard and generate your first PDF in under five minutes.

PDF Generation in Python (FastAPI + DocuForge)

Fred T — Tue, 17 Mar 2026 17:00:00 +0000

Introduction

Python dominates backend development and data pipelines for good reason: its ecosystem is vast, its syntax is readable, and frameworks like FastAPI make building production-grade APIs remarkably straightforward. When those APIs need to produce PDFs -- invoices, reports, shipping labels, compliance documents -- most teams reach for libraries like ReportLab or WeasyPrint, then spend days wrestling with layout quirks and font rendering.

DocuForge takes a different approach. Instead of generating PDFs locally, you send HTML (or a template reference) to the DocuForge API and get back a pixel-perfect PDF. The official Python SDK wraps this workflow with httpx for HTTP transport and Pydantic v2 for response validation, so everything feels native to a modern Python stack.

In this tutorial you will build a FastAPI application with three PDF endpoints: one that converts raw HTML, one that uses a stored template, and one that streams a PDF file download directly to the browser. By the end you will have a working service you can deploy behind any ASGI server.

Step 1: Install Dependencies

Start by creating a new project directory and installing the three packages you need.

mkdir fastapi-pdf && cd fastapi-pdf
python -m venv .venv && source .venv/bin/activate
pip install docuforge fastapi uvicorn

Next, set your DocuForge API key as an environment variable. You can grab one from the DocuForge dashboard.

export DOCUFORGE_API_KEY="df_live_your_key_here"

You will reference this variable throughout the application with os.environ. Never hard-code API keys in source files.

Step 2: Basic HTML-to-PDF Endpoint

Create a file called main.py and add the following code. This first endpoint accepts an HTML string in the request body and returns the URL of the generated PDF.

import os
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from docuforge import DocuForge

app = FastAPI(title="PDF Service")

DOCUFORGE_API_KEY = os.environ["DOCUFORGE_API_KEY"]


class GenerateRequest(BaseModel):
    html: str
    format: str = "A4"
    margin: str = "20mm"


@app.post("/generate")
def generate_pdf(req: GenerateRequest):
    with DocuForge(api_key=DOCUFORGE_API_KEY) as df:
        pdf = df.generate(
            html=req.html,
            options={
                "format": req.format,
                "margin": req.margin,
                "printBackground": True,
            },
        )

    return {
        "id": pdf.id,
        "url": pdf.url,
        "status": pdf.status,
        "pages": pdf.pages,
        "file_size": pdf.file_size,
        "generation_time_ms": pdf.generation_time_ms,
    }

A few things to note here. The DocuForge client is used as a context manager (with), which ensures the underlying httpx connection is properly closed after the request completes. The options dictionary maps directly to the Chromium PDF rendering settings that DocuForge supports -- format, margin, orientation, header, footer, and printBackground are the most common.

The response object exposes every field you need for downstream processing. pdf.url is a signed URL where the generated file can be downloaded. pdf.generation_time_ms is useful for performance monitoring. pdf.pages tells you the page count, which matters if you bill clients per page.

Start the server to verify everything works:

uvicorn main:app --reload --port 8000

Test with curl:

curl -X POST http://localhost:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello from FastAPI</h1><p>Generated at runtime.</p>"}'

You should receive a JSON response containing the PDF URL within a few hundred milliseconds.

Step 3: Template-Based Generation

Hard-coding HTML in every request works for simple cases, but most production applications use templates. DocuForge templates use Handlebars syntax for variable interpolation, loops, and conditionals. You create a template once, then generate PDFs by passing in data.

First, create a template. You can do this from the dashboard or programmatically:

with DocuForge(api_key=DOCUFORGE_API_KEY) as df:
    template = df.templates.create(
        name="invoice",
        html_content="""
        <html>
        <body style="font-family: sans-serif; padding: 40px;">
            <h1>Invoice #{{invoice_number}}</h1>
            <p>Bill to: {{customer_name}}</p>
            <table style="width: 100%; border-collapse: collapse;">
                <tr style="border-bottom: 1px solid #ccc;">
                    <th style="text-align: left;">Item</th>
                    <th style="text-align: right;">Amount</th>
                </tr>
                {{#each items}}
                <tr style="border-bottom: 1px solid #eee;">
                    <td>{{this.description}}</td>
                    <td style="text-align: right;">${{this.amount}}</td>
                </tr>
                {{/each}}
            </table>
            <h2 style="text-align: right; margin-top: 20px;">Total: ${{total}}</h2>
        </body>
        </html>
        """,
        schema={
            "invoice_number": "string",
            "customer_name": "string",
            "items": "array",
            "total": "number",
        },
    )
    print(f"Template created: {template.id}")

Save the returned template ID (it will look like tmpl_...). Now add an endpoint that generates invoices from this template:

class InvoiceRequest(BaseModel):
    invoice_number: str
    customer_name: str
    items: list[dict]
    total: float


INVOICE_TEMPLATE_ID = "tmpl_your_template_id"


@app.post("/invoice")
def generate_invoice(req: InvoiceRequest):
    with DocuForge(api_key=DOCUFORGE_API_KEY) as df:
        pdf = df.from_template(
            template=INVOICE_TEMPLATE_ID,
            data=req.model_dump(),
            options={"format": "A4", "margin": "20mm"},
        )

    return {"id": pdf.id, "url": pdf.url, "pages": pdf.pages}

The Pydantic model validates incoming data before it reaches DocuForge, giving you clear error messages at the API boundary. The data parameter accepts a plain dictionary, so req.model_dump() converts the validated model directly. This pattern -- Pydantic for validation, DocuForge for rendering -- keeps your endpoint logic minimal.

Step 4: File Download Endpoint

Sometimes you do not want to redirect the client to a URL. Instead, you want to stream the PDF bytes directly as a file download. DocuForge supports this through the output="base64" option, which returns the PDF content as a base64-encoded string instead of a hosted URL.

import base64
from fastapi import Response


class DownloadRequest(BaseModel):
    html: str
    filename: str = "document.pdf"


@app.post("/download")
def download_pdf(req: DownloadRequest):
    with DocuForge(api_key=DOCUFORGE_API_KEY) as df:
        pdf = df.generate(
            html=req.html,
            options={"format": "A4", "margin": "20mm"},
            output="base64",
        )

    pdf_bytes = base64.b64decode(pdf.data)

    return Response(
        content=pdf_bytes,
        media_type="application/pdf",
        headers={
            "Content-Disposition": f'attachment; filename="{req.filename}"',
            "Content-Length": str(len(pdf_bytes)),
        },
    )

When output is set to "base64", the response object includes a .data attribute containing the encoded PDF. You decode it with the standard library base64.b64decode, then return it wrapped in a FastAPI Response with the appropriate media type and Content-Disposition header.

The Content-Disposition header controls whether the browser downloads the file (attachment) or displays it inline (inline). For most API use cases, attachment is the right choice. You can also pass the filename through from the client, as shown above.

This approach avoids an extra redirect and works well for internal services, serverless functions, or any context where the client should receive the PDF in a single request-response cycle.

Step 5: Error Handling

The DocuForge SDK raises specific exception types that map cleanly to HTTP status codes. You should catch these and convert them to FastAPI HTTPException responses so your API returns consistent error shapes.

from docuforge import (
    AuthenticationError,
    RateLimitError,
    ValidationError,
    DocuForgeError,
)


@app.post("/generate-safe")
def generate_pdf_safe(req: GenerateRequest):
    try:
        with DocuForge(api_key=DOCUFORGE_API_KEY) as df:
            pdf = df.generate(
                html=req.html,
                options={"format": req.format, "margin": req.margin},
            )
        return {"id": pdf.id, "url": pdf.url}

    except AuthenticationError:
        raise HTTPException(
            status_code=401,
            detail="Invalid DocuForge API key. Check your DOCUFORGE_API_KEY.",
        )
    except RateLimitError:
        raise HTTPException(
            status_code=429,
            detail="Rate limit exceeded. Please retry after a short delay.",
        )
    except ValidationError as e:
        raise HTTPException(
            status_code=400,
            detail=f"Invalid request: {e}",
        )
    except DocuForgeError as e:
        raise HTTPException(
            status_code=502,
            detail=f"PDF generation failed: {e}",
        )

AuthenticationError fires when the API key is missing, malformed, or revoked. RateLimitError indicates you have exceeded your plan's per-second request limit. ValidationError means the HTML or options you sent were rejected by the API (for example, an unsupported page format). The base DocuForgeError catches everything else, including network failures and server errors.

For production services, you may prefer to register these as global exception handlers with FastAPI's @app.exception_handler decorator rather than repeating try/except blocks in every endpoint.

Step 6: Running in an Async Context

The DocuForge Python SDK uses a synchronous httpx client internally. FastAPI endpoints defined with def (not async def) run in a thread pool automatically, so the synchronous SDK works without blocking the event loop. However, if you need to call DocuForge from an async def endpoint -- perhaps because the same endpoint performs other async I/O -- you should offload the synchronous call to an executor.

import asyncio
from functools import partial


@app.post("/generate-async")
async def generate_pdf_async(req: GenerateRequest):
    loop = asyncio.get_event_loop()

    def _generate():
        with DocuForge(api_key=DOCUFORGE_API_KEY) as df:
            return df.generate(
                html=req.html,
                options={"format": req.format, "margin": req.margin},
            )

    pdf = await loop.run_in_executor(None, _generate)

    return {"id": pdf.id, "url": pdf.url, "pages": pdf.pages}

Passing None as the first argument to run_in_executor uses the default thread pool executor. The inner _generate function runs in a separate thread, keeping the event loop free for other requests.

If you have a high-throughput service and want to avoid the thread pool entirely, you can bypass the SDK and call the DocuForge REST API directly with httpx.AsyncClient:

import httpx


async def generate_pdf_native(html: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.docuforge.com/v1/generate",
            headers={"Authorization": f"Bearer {DOCUFORGE_API_KEY}"},
            json={"html": html, "options": {"format": "A4"}},
            timeout=30.0,
        )
        response.raise_for_status()
        return response.json()

This is more verbose but gives you full async control. For most applications, the run_in_executor approach is simpler and sufficient.

Complete Application Code

Here is the consolidated main.py with all endpoints, error handling, and the async variant combined into a single runnable file.

import os
import base64
import asyncio
from fastapi import FastAPI, HTTPException, Response
from pydantic import BaseModel
from docuforge import (
    DocuForge,
    AuthenticationError,
    RateLimitError,
    ValidationError,
    DocuForgeError,
)

app = FastAPI(title="PDF Service")

DOCUFORGE_API_KEY = os.environ["DOCUFORGE_API_KEY"]
INVOICE_TEMPLATE_ID = os.environ.get("INVOICE_TEMPLATE_ID", "tmpl_your_template_id")


# --- Request Models ---

class GenerateRequest(BaseModel):
    html: str
    format: str = "A4"
    margin: str = "20mm"


class InvoiceRequest(BaseModel):
    invoice_number: str
    customer_name: str
    items: list[dict]
    total: float


class DownloadRequest(BaseModel):
    html: str
    filename: str = "document.pdf"


# --- Error Handling ---

def handle_docuforge_error(e: Exception):
    if isinstance(e, AuthenticationError):
        raise HTTPException(status_code=401, detail="Invalid DocuForge API key.")
    elif isinstance(e, RateLimitError):
        raise HTTPException(status_code=429, detail="Rate limit exceeded.")
    elif isinstance(e, ValidationError):
        raise HTTPException(status_code=400, detail=f"Invalid request: {e}")
    elif isinstance(e, DocuForgeError):
        raise HTTPException(status_code=502, detail=f"PDF generation failed: {e}")
    raise e


# --- Endpoints ---

@app.post("/generate")
def generate_pdf(req: GenerateRequest):
    try:
        with DocuForge(api_key=DOCUFORGE_API_KEY) as df:
            pdf = df.generate(
                html=req.html,
                options={
                    "format": req.format,
                    "margin": req.margin,
                    "printBackground": True,
                },
            )
        return {
            "id": pdf.id,
            "url": pdf.url,
            "status": pdf.status,
            "pages": pdf.pages,
            "file_size": pdf.file_size,
            "generation_time_ms": pdf.generation_time_ms,
        }
    except (AuthenticationError, RateLimitError, ValidationError, DocuForgeError) as e:
        handle_docuforge_error(e)


@app.post("/invoice")
def generate_invoice(req: InvoiceRequest):
    try:
        with DocuForge(api_key=DOCUFORGE_API_KEY) as df:
            pdf = df.from_template(
                template=INVOICE_TEMPLATE_ID,
                data=req.model_dump(),
                options={"format": "A4", "margin": "20mm"},
            )
        return {"id": pdf.id, "url": pdf.url, "pages": pdf.pages}
    except (AuthenticationError, RateLimitError, ValidationError, DocuForgeError) as e:
        handle_docuforge_error(e)


@app.post("/download")
def download_pdf(req: DownloadRequest):
    try:
        with DocuForge(api_key=DOCUFORGE_API_KEY) as df:
            pdf = df.generate(
                html=req.html,
                options={"format": "A4", "margin": "20mm"},
                output="base64",
            )
        pdf_bytes = base64.b64decode(pdf.data)
        return Response(
            content=pdf_bytes,
            media_type="application/pdf",
            headers={
                "Content-Disposition": f'attachment; filename="{req.filename}"',
                "Content-Length": str(len(pdf_bytes)),
            },
        )
    except (AuthenticationError, RateLimitError, ValidationError, DocuForgeError) as e:
        handle_docuforge_error(e)


@app.post("/generate-async")
async def generate_pdf_async(req: GenerateRequest):
    loop = asyncio.get_event_loop()

    def _generate():
        with DocuForge(api_key=DOCUFORGE_API_KEY) as df:
            return df.generate(
                html=req.html,
                options={"format": req.format, "margin": req.margin},
            )

    try:
        pdf = await loop.run_in_executor(None, _generate)
        return {"id": pdf.id, "url": pdf.url, "pages": pdf.pages}
    except (AuthenticationError, RateLimitError, ValidationError, DocuForgeError) as e:
        handle_docuforge_error(e)


@app.get("/health")
def health():
    return {"status": "ok"}

Run the complete application:

export DOCUFORGE_API_KEY="df_live_your_key_here"
uvicorn main:app --reload --port 8000

FastAPI automatically generates interactive API documentation at http://localhost:8000/docs, where you can test each endpoint directly from the browser.

Going Further

This tutorial covered the core patterns for integrating DocuForge into a FastAPI application. From here you can explore several directions:

Django integration -- If your project uses Django rather than FastAPI, the SDK works identically. See our Django tutorial for middleware patterns and class-based view examples.
Batch generation -- The df.batch() method queues multiple PDFs for asynchronous processing, which is ideal for monthly invoice runs or report pipelines.
Page layout control -- Our page layout guide covers headers, footers, page numbers, and multi-column layouts in detail.
Comparison with local rendering -- If you are evaluating DocuForge against Puppeteer or WeasyPrint, the DocuForge vs Puppeteer article breaks down the trade-offs in performance, accuracy, and operational overhead.

How to Generate PDFs in Next.js with DocuForge

Fred T — Tue, 17 Mar 2026 13:00:00 +0000

How to Generate PDFs in Next.js with DocuForge

If you have built anything beyond a toy Next.js application, you have probably run into the need to generate PDFs. Invoices after a successful checkout. Monthly reports for a dashboard. Receipts emailed to customers. Shipping labels. The list goes on.

The naive approach is to reach for a browser-based library and render PDFs on the client. That works for simple cases, but it falls apart quickly. You leak API keys. You lose control over layout consistency across browsers. And you burden the user's device with heavy rendering work.

Server-side PDF generation solves all of that. Your API keys stay on the server. You get pixel-perfect output from a headless Chromium instance. And you can generate PDFs asynchronously without blocking the UI.

In this tutorial, you will build a complete PDF generation flow in a Next.js 14 application using DocuForge. By the end, you will have an API route that generates PDFs from raw HTML, a reusable template system with Handlebars, headers and footers with page numbers, and a clean client-side download button.

Prerequisites

Before you start, make sure you have the following:

Next.js 14+ with the App Router enabled
A DocuForge account and API key (grab one from the dashboard)
Node.js 18 or later

That is everything. No Puppeteer installation, no Chromium binaries, no wkhtmltopdf nightmares.

Step 1: Install the SDK

Install the docuforge npm package in your Next.js project:

npm install docuforge

Then add your API key to .env.local. Never commit this file to version control.

DOCUFORGE_API_KEY=df_live_your_api_key_here

The SDK reads this key when you instantiate the client. Since Next.js API routes and Server Actions run on the server, the key is never exposed to the browser. This is exactly why server-side generation matters.

With the SDK installed, you are ready to write your first API route.

Step 2: Create a Server-Side API Route

Create a new file at app/api/generate-pdf/route.ts. This route will accept a POST request with HTML content and return a generated PDF.

// app/api/generate-pdf/route.ts
import { NextRequest, NextResponse } from "next/server";
import DocuForge from "docuforge";

const df = new DocuForge(process.env.DOCUFORGE_API_KEY!);

export async function POST(request: NextRequest) {
  try {
    const { html } = await request.json();

    if (!html) {
      return NextResponse.json(
        { error: "Missing html field in request body" },
        { status: 400 }
      );
    }

    const result = await df.generate({
      html,
      options: {
        format: "A4",
        margin: { top: "20mm", right: "15mm", bottom: "20mm", left: "15mm" },
        printBackground: true,
      },
    });

    return NextResponse.json(result);
  } catch (error) {
    console.error("PDF generation failed:", error);
    return NextResponse.json(
      { error: "Failed to generate PDF" },
      { status: 500 }
    );
  }
}

The df.generate() call sends your HTML to DocuForge's rendering pipeline, which uses a headless Chromium instance to produce a pixel-perfect PDF. The response includes everything you need:

{
  "id": "gen_abc123xyz",
  "status": "completed",
  "url": "https://storage.docuforge.com/pdfs/gen_abc123xyz.pdf",
  "pages": 1,
  "file_size": 48210,
  "generation_time_ms": 320
}

The url field is a direct link to the generated PDF. You can redirect users to it, embed it in an iframe, or download it programmatically. The id field lets you look up the generation later in your history.

Notice that the DocuForge client is instantiated outside the handler. This avoids creating a new client on every request and keeps the connection efficient.

Step 3: Build a Client-Side Download Button

Now wire up a React component that calls your API route and opens the generated PDF. Create a new file at app/components/pdf-download-button.tsx.

// app/components/pdf-download-button.tsx
"use client";

import { useState } from "react";

interface PdfDownloadButtonProps {
  html: string;
  label?: string;
}

export function PdfDownloadButton({
  html,
  label = "Download PDF",
}: PdfDownloadButtonProps) {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  async function handleGenerate() {
    setLoading(true);
    setError(null);

    try {
      const response = await fetch("/api/generate-pdf", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ html }),
      });

      if (!response.ok) {
        const data = await response.json();
        throw new Error(data.error || "Generation failed");
      }

      const result = await response.json();
      window.open(result.url, "_blank");
    } catch (err) {
      setError(err instanceof Error ? err.message : "Something went wrong");
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button
        onClick={handleGenerate}
        disabled={loading}
        className="rounded-md bg-orange-500 px-4 py-2 text-white font-medium
                   hover:bg-orange-600 disabled:opacity-50 disabled:cursor-not-allowed"
      >
        {loading ? "Generating..." : label}
      </button>
      {error && <p className="mt-2 text-sm text-red-500">{error}</p>}
    </div>
  );
}

Use it anywhere in your app by passing an HTML string:

<PdfDownloadButton
  html="<h1>Hello from DocuForge</h1><p>This is a generated PDF.</p>"
  label="Generate Invoice"
/>

The component handles three states: idle, loading, and error. When the PDF is ready, it opens in a new tab. In a production app, you might want to trigger a file download instead by fetching the PDF URL as a blob and using a temporary anchor element. But for most use cases, opening the URL directly is the simplest approach.

Step 4: Use Templates for Production Layouts

Hardcoding HTML strings works for prototyping, but production applications need reusable templates. DocuForge templates use Handlebars syntax, which gives you variables, loops, and conditionals without the overhead of a full templating engine on your side.

First, create a template. You would typically do this once, either through the dashboard or programmatically during setup:

// scripts/create-invoice-template.ts
import DocuForge from "docuforge";

const df = new DocuForge(process.env.DOCUFORGE_API_KEY!);

async function createTemplate() {
  const template = await df.templates.create({
    name: "Invoice",
    html_content: `
      <html>
        <head>
          <style>
            body { font-family: 'Helvetica', sans-serif; padding: 40px; color: #1a1a1a; }
            .header { display: flex; justify-content: space-between; margin-bottom: 40px; }
            .company { font-size: 24px; font-weight: bold; }
            .invoice-number { color: #666; font-size: 14px; }
            table { width: 100%; border-collapse: collapse; margin-top: 30px; }
            th { text-align: left; border-bottom: 2px solid #1a1a1a; padding: 10px 0; }
            td { padding: 10px 0; border-bottom: 1px solid #eee; }
            .total { font-size: 20px; font-weight: bold; text-align: right; margin-top: 30px; }
          </style>
        </head>
        <body>
          <div class="header">
            <div class="company">{{companyName}}</div>
            <div class="invoice-number">Invoice #{{invoiceNumber}}</div>
          </div>
          <p>Bill to: <strong>{{customerName}}</strong></p>
          <p>Date: {{date}}</p>
          <table>
            <thead>
              <tr>
                <th>Item</th>
                <th>Quantity</th>
                <th>Price</th>
              </tr>
            </thead>
            <tbody>
              {{#each items}}
              <tr>
                <td>{{this.name}}</td>
                <td>{{this.quantity}}</td>
                <td>\${{this.price}}</td>
              </tr>
              {{/each}}
            </tbody>
          </table>
          <div class="total">Total: \${{total}}</div>
        </body>
      </html>
    `,
    schema: {
      companyName: "string",
      invoiceNumber: "string",
      customerName: "string",
      date: "string",
      items: "array",
      total: "number",
    },
  });

  console.log("Template created:", template.id);
}

createTemplate();

Now generate PDFs from that template by passing the template ID and your data:

// In your API route or Server Action
const result = await df.fromTemplate({
  template: "tmpl_abc123", // your template ID
  data: {
    companyName: "Acme Corp",
    invoiceNumber: "INV-2026-0042",
    customerName: "Jane Smith",
    date: "March 10, 2026",
    items: [
      { name: "Pro Plan (Annual)", quantity: 1, price: "299.00" },
      { name: "Extra Storage (100GB)", quantity: 2, price: "49.00" },
    ],
    total: 397.0,
  },
  options: {
    format: "A4",
    margin: "20mm",
  },
});

The Handlebars syntax keeps your templates readable. {{#each items}} iterates over the array, and {{#if condition}} lets you conditionally show sections like a discount line or tax breakdown.

Templates also support versioning. Every time you update a template through the API or dashboard, DocuForge saves the previous version. You can list versions, view any historical snapshot, and restore if something goes wrong. This is critical for compliance-heavy documents where you need to prove what a template looked like on a specific date.

Step 5: Add Headers, Footers, and Page Numbers

Multi-page documents like contracts and reports need consistent headers and footers. DocuForge supports HTML-based headers and footers with two special interpolation variables: {{pageNumber}} and {{totalPages}}.

const result = await df.generate({
  html: longReportHtml,
  options: {
    format: "A4",
    margin: { top: "35mm", right: "15mm", bottom: "25mm", left: "15mm" },
    printBackground: true,
    header: `
      <div style="font-size: 10px; color: #888; width: 100%; padding: 0 15mm;
                  display: flex; justify-content: space-between;">
        <span>Acme Corp - Confidential</span>
        <span>Q1 2026 Report</span>
      </div>
    `,
    footer: `
      <div style="font-size: 10px; color: #888; width: 100%; text-align: center;
                  padding: 0 15mm;">
        Page {{pageNumber}} of {{totalPages}}
      </div>
    `,
  },
});

A few things to keep in mind with headers and footers. The top margin must be large enough to accommodate the header height, and the bottom margin must fit the footer. If your margin is too small, the header or footer will overlap with the document body. A top margin of 30-35mm works well for a single-line header.

Headers and footers are rendered independently from the main document body. They have their own rendering context, so styles defined in your main HTML do not cascade into them. Inline styles are the most reliable approach here.

The {{pageNumber}} and {{totalPages}} placeholders are replaced at render time by the PDF engine. They work in both headers and footers, and you can use them multiple times.

Step 6: Server Actions Alternative

If you prefer to skip the API route entirely, Next.js Server Actions offer a more streamlined approach. Server Actions run on the server and can be called directly from client components without an explicit fetch.

Create a Server Action file:

// app/actions/generate-pdf.ts
"use server";

import DocuForge from "docuforge";

const df = new DocuForge(process.env.DOCUFORGE_API_KEY!);

interface GeneratePdfInput {
  html?: string;
  templateId?: string;
  data?: Record<string, unknown>;
}

export async function generatePdf(input: GeneratePdfInput) {
  try {
    let result;

    if (input.templateId && input.data) {
      result = await df.fromTemplate({
        template: input.templateId,
        data: input.data,
        options: {
          format: "A4",
          margin: "20mm",
          printBackground: true,
        },
      });
    } else if (input.html) {
      result = await df.generate({
        html: input.html,
        options: {
          format: "A4",
          margin: "20mm",
          printBackground: true,
        },
      });
    } else {
      throw new Error("Provide either html or templateId with data");
    }

    return { success: true, url: result.url, id: result.id };
  } catch (error) {
    console.error("PDF generation failed:", error);
    return { success: false, error: "Failed to generate PDF" };
  }
}

Then call it from any client component:

"use client";

import { useState } from "react";
import { generatePdf } from "@/app/actions/generate-pdf";

export function InvoiceGenerator() {
  const [loading, setLoading] = useState(false);

  async function handleGenerate() {
    setLoading(true);

    const result = await generatePdf({
      templateId: "tmpl_abc123",
      data: {
        companyName: "Acme Corp",
        invoiceNumber: "INV-2026-0042",
        customerName: "Jane Smith",
        date: "March 10, 2026",
        items: [
          { name: "Pro Plan", quantity: 1, price: "299.00" },
        ],
        total: 299.0,
      },
    });

    if (result.success && result.url) {
      window.open(result.url, "_blank");
    }

    setLoading(false);
  }

  return (
    <button onClick={handleGenerate} disabled={loading}>
      {loading ? "Generating..." : "Generate Invoice"}
    </button>
  );
}

The Server Action approach has a few advantages. There is no need to define or maintain a separate API route. Type safety flows directly from the action to the component. And Next.js handles the serialization and network call under the hood.

The tradeoff is that Server Actions are tightly coupled to your Next.js app. If you also need to generate PDFs from a mobile app or an external service, an API route gives you a reusable endpoint. Choose based on your use case.

Going Further

You now have a solid foundation for PDF generation in Next.js. From here, there are several directions to explore depending on your use case:

Automate Stripe invoices -- Generate and email PDF invoices on every successful payment using Stripe webhooks.
Export React components to PDF -- Use df.fromReact() to render your existing React components directly to PDF without maintaining separate HTML templates.
DocuForge vs Puppeteer -- Understand the tradeoffs between a managed API and self-hosted browser automation.
Generate PDFs in Express -- If your backend is not Next.js, the same SDK works in any Node.js environment.

Check out the full API reference for advanced features like batch generation, webhook callbacks, and PDF tools including merge, split, and password protection.

Express.js PDF API: From HTML to PDF in 30 Seconds

Fred T — Mon, 16 Mar 2026 17:00:00 +0000

Express.js PDF API: From HTML to PDF in 30 Seconds

Express.js remains the most widely used Node.js framework for building APIs. It has earned that position by staying out of your way. You define routes, wire up middleware, and ship. PDF generation should be just as straightforward.

In practice, it rarely is. Teams burn days configuring Puppeteer, managing headless Chromium processes, handling zombie browsers, and debugging font rendering. All of that complexity exists below the abstraction layer you actually care about: give me HTML, give me back a PDF.

DocuForge eliminates that entire layer. You send HTML (or a template, or JSX) to a single API call and get a production-ready PDF back. No browser binaries. No process management. No memory leaks at 3 AM.

In this tutorial, you will build a PDF microservice with Express.js that exposes four endpoints: HTML-to-PDF generation, template-based invoice rendering, direct file downloads, and React-to-PDF conversion. The whole thing takes about 30 seconds to set up and a few more minutes to flesh out with proper error handling.

Step 1: Project Setup

Start by creating a new project and installing the two packages you need:

mkdir pdf-service && cd pdf-service
npm init -y
npm install express docuforge
npm install -D typescript @types/express @types/node tsx

TypeScript is optional but recommended. If you prefer plain JavaScript, skip the dev dependencies and remove the type annotations from the examples below.

Create a tsconfig.json with sensible defaults:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true
  }
}

Add your DocuForge API key to a .env file. Never commit this file to version control.

DOCUFORGE_API_KEY=df_live_your_api_key_here

Now initialize the DocuForge client. Create src/server.ts and add the foundation:

// src/server.ts
import express from "express";
import DocuForge from "docuforge";

const app = express();
app.use(express.json({ limit: "10mb" }));

const df = new DocuForge(process.env.DOCUFORGE_API_KEY!);

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`PDF service running on port ${PORT}`);
});

Run it with npx tsx --env-file=.env src/server.ts. You have a running Express server with a configured DocuForge client. Time to add endpoints.

Step 2: HTML-to-PDF Endpoint

The most fundamental operation is converting raw HTML into a PDF. Create a POST /api/generate route that accepts an HTML string and optional PDF settings:

app.post("/api/generate", async (req, res, next) => {
  try {
    const { html, options } = req.body;

    if (!html) {
      res.status(400).json({ error: "Missing html field in request body" });
      return;
    }

    const pdf = await df.generate({
      html,
      options: {
        format: "A4",
        margin: { top: "20mm", right: "15mm", bottom: "20mm", left: "15mm" },
        printBackground: true,
        ...options,
      },
    });

    res.json({
      id: pdf.id,
      url: pdf.url,
      pages: pdf.pages,
      file_size: pdf.file_size,
      generation_time_ms: pdf.generation_time_ms,
    });
  } catch (err) {
    next(err);
  }
});

Test it with curl:

curl -X POST http://localhost:3000/api/generate \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello from Express</h1><p>This is a PDF.</p>"}'

The response comes back with a url field pointing to the hosted PDF. You can open it in a browser, pass it to a frontend, or store it in your database. The generation_time_ms field tells you exactly how long the render took, typically under a second for simple documents.

Notice the options spread pattern. The caller can override any PDF setting (format, orientation, margins) through the request body, while your defaults ensure sensible output when no options are provided. The printBackground flag is worth defaulting to true since most HTML documents use background colors and images that would otherwise be stripped.

You can also add headers and footers with automatic page numbering:

const pdf = await df.generate({
  html,
  options: {
    format: "A4",
    margin: { top: "25mm", right: "15mm", bottom: "25mm", left: "15mm" },
    header: '<div style="font-size:10px;text-align:center;width:100%">Confidential</div>',
    footer: '<div style="font-size:10px;text-align:center;width:100%">Page {{pageNumber}} of {{totalPages}}</div>',
  },
});

The {{pageNumber}} and {{totalPages}} tokens are interpolated automatically by DocuForge during rendering.

Step 3: Template-Based Invoice Endpoint

Raw HTML works for one-off documents, but most real applications generate PDFs from structured data. Invoices, receipts, reports -- these all follow a fixed layout populated with dynamic values. DocuForge templates use Handlebars syntax ({{variable}}, {{#each items}}, {{#if}}) and are stored server-side with version history.

Create a template in the DocuForge dashboard first (or via the API), then reference it by ID:

const INVOICE_TEMPLATE_ID = "tmpl_your_invoice_template";

app.post("/api/invoices/:id/pdf", async (req, res, next) => {
  try {
    const invoiceId = req.params.id;

    // Fetch invoice data from your database
    const invoice = await getInvoiceFromDB(invoiceId);

    if (!invoice) {
      res.status(404).json({ error: "Invoice not found" });
      return;
    }

    const pdf = await df.fromTemplate({
      template: INVOICE_TEMPLATE_ID,
      data: {
        invoiceNumber: invoice.number,
        date: invoice.date,
        customerName: invoice.customer.name,
        customerEmail: invoice.customer.email,
        items: invoice.lineItems.map((item) => ({
          description: item.description,
          quantity: item.quantity,
          unitPrice: (item.unitPrice / 100).toFixed(2),
          total: ((item.quantity * item.unitPrice) / 100).toFixed(2),
        })),
        subtotal: (invoice.subtotal / 100).toFixed(2),
        tax: (invoice.tax / 100).toFixed(2),
        total: (invoice.total / 100).toFixed(2),
      },
      options: {
        format: "A4",
        margin: "15mm",
      },
    });

    res.json({
      id: pdf.id,
      url: pdf.url,
      pages: pdf.pages,
      generation_time_ms: pdf.generation_time_ms,
    });
  } catch (err) {
    next(err);
  }
});

The data object is matched against the Handlebars placeholders in your template. If your template contains {{#each items}}, the items array is iterated. If it contains {{#if customerEmail}}, the block renders conditionally. This separation of layout and data means designers can update the template in the dashboard without touching your Express code.

Templates also support version history. Every update to a template creates a new version, so you can roll back if a layout change breaks something. The template ID stays the same across versions -- DocuForge always uses the latest version unless you specify otherwise.

Step 4: Direct File Download

Sometimes you do not want to redirect users to a hosted URL. You want the browser to start downloading a PDF immediately when they click a button. The output: 'base64' option makes this possible.

app.get("/api/invoices/:id/download", async (req, res, next) => {
  try {
    const invoiceId = req.params.id;
    const invoice = await getInvoiceFromDB(invoiceId);

    if (!invoice) {
      res.status(404).json({ error: "Invoice not found" });
      return;
    }

    const pdf = await df.fromTemplate({
      template: INVOICE_TEMPLATE_ID,
      data: {
        invoiceNumber: invoice.number,
        date: invoice.date,
        customerName: invoice.customer.name,
        items: invoice.lineItems,
        total: (invoice.total / 100).toFixed(2),
      },
      output: "base64",
    });

    const buffer = Buffer.from(pdf.data!, "base64");

    res.setHeader("Content-Type", "application/pdf");
    res.setHeader(
      "Content-Disposition",
      `attachment; filename="invoice-${invoice.number}.pdf"`
    );
    res.setHeader("Content-Length", buffer.length);
    res.send(buffer);
  } catch (err) {
    next(err);
  }
});

When output is set to 'base64', the response includes a data field containing the raw PDF bytes encoded as a base64 string. You decode it into a Buffer, set the appropriate headers, and send it directly. The Content-Disposition: attachment header tells the browser to download the file rather than display it inline.

This approach keeps everything in a single request. The user clicks a link, the server generates the PDF, and the download starts. No intermediate hosted URL, no second HTTP call.

If you prefer the hosted URL approach but still want a seamless download experience, you can use the default output: 'url' mode and redirect:

app.get("/api/invoices/:id/download-redirect", async (req, res, next) => {
  try {
    const invoice = await getInvoiceFromDB(req.params.id);
    const pdf = await df.fromTemplate({
      template: INVOICE_TEMPLATE_ID,
      data: { invoiceNumber: invoice.number, items: invoice.lineItems },
    });
    res.redirect(pdf.url);
  } catch (err) {
    next(err);
  }
});

This is faster since the PDF is generated and stored on DocuForge's CDN, and the browser fetches it directly. The tradeoff is that the URL is temporarily public. For sensitive documents like invoices, the base64 approach keeps the PDF entirely within your server's control.

Step 5: Error Handling Middleware

DocuForge's SDK throws typed errors that map cleanly to HTTP status codes. A single Express error middleware can catch them all and return consistent responses:

import {
  DocuForgeError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
} from "docuforge";

app.use(
  (
    err: Error,
    req: express.Request,
    res: express.Response,
    next: express.NextFunction
  ) => {
    if (err instanceof RateLimitError) {
      res.setHeader("Retry-After", String(err.retryAfter));
      res.status(429).json({
        error: "Rate limit exceeded",
        retryAfter: err.retryAfter,
      });
      return;
    }

    if (err instanceof AuthenticationError) {
      res.status(401).json({
        error: "Invalid or missing DocuForge API key",
      });
      return;
    }

    if (err instanceof ValidationError) {
      res.status(400).json({
        error: err.message,
      });
      return;
    }

    if (err instanceof DocuForgeError) {
      res.status(err.statusCode).json({
        error: err.message,
      });
      return;
    }

    // Unknown errors
    console.error("Unexpected error:", err);
    res.status(500).json({
      error: "Internal server error",
    });
  }
);

The order matters. RateLimitError and AuthenticationError extend DocuForgeError, so they must be checked first. If you catch DocuForgeError at the top, the specific subclasses would never match.

The RateLimitError is particularly important to handle well. It includes a retryAfter property (in seconds) that you should forward as a Retry-After header. Well-behaved clients will wait that duration before retrying. If you are building a frontend that calls this Express API, you can read that header and show a countdown or queue the request.

The ValidationError covers cases like malformed HTML, missing template variables, or invalid PDF options. The error message from DocuForge is descriptive enough to return directly to the caller.

Because every route uses next(err) in its catch block, all DocuForge errors flow through this single middleware. You write the error mapping once and every endpoint benefits.

Step 6: React-to-PDF Endpoint

If your team writes components in React, you can skip the HTML string entirely and send JSX to DocuForge. The server transpiles it, renders it to static markup, and converts it to a PDF:

app.post("/api/generate/react", async (req, res, next) => {
  try {
    const { react, data, styles } = req.body;

    if (!react) {
      res.status(400).json({ error: "Missing react field in request body" });
      return;
    }

    const pdf = await df.fromReact({
      react,
      data,
      styles,
      options: {
        format: "A4",
        margin: "20mm",
        printBackground: true,
      },
    });

    res.json({
      id: pdf.id,
      url: pdf.url,
      pages: pdf.pages,
      file_size: pdf.file_size,
      generation_time_ms: pdf.generation_time_ms,
    });
  } catch (err) {
    next(err);
  }
});

The react field accepts a JSX/TSX string. DocuForge transpiles it with esbuild on the server, so you do not need a build step. The optional data object is passed as props to the root component, and styles accepts a CSS string applied to the rendered output.

This is especially useful when your PDF layouts share components with your frontend. Instead of maintaining separate HTML templates, you write React components that work in both the browser and the PDF renderer. A reporting dashboard component, for example, can render interactively on screen and produce a static PDF with the same layout when exported.

curl -X POST http://localhost:3000/api/generate/react \
  -H "Content-Type: application/json" \
  -d '{
    "react": "export default function Report({ title, items }) { return (<div><h1>{title}</h1><ul>{items.map((item, i) => <li key={i}>{item}</li>)}</ul></div>); }",
    "data": { "title": "Q1 Report", "items": ["Revenue up 23%", "Churn down 4%"] }
  }'

Complete Server Code

Here is the full src/server.ts with all endpoints consolidated:

// src/server.ts
import express from "express";
import DocuForge, {
  DocuForgeError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
} from "docuforge";

const app = express();
app.use(express.json({ limit: "10mb" }));

const df = new DocuForge(process.env.DOCUFORGE_API_KEY!);
const INVOICE_TEMPLATE_ID = "tmpl_your_invoice_template";

// Health check
app.get("/health", (req, res) => {
  res.json({ status: "ok" });
});

// HTML-to-PDF
app.post("/api/generate", async (req, res, next) => {
  try {
    const { html, options } = req.body;
    if (!html) {
      res.status(400).json({ error: "Missing html field" });
      return;
    }
    const pdf = await df.generate({
      html,
      options: { format: "A4", margin: "15mm", printBackground: true, ...options },
    });
    res.json(pdf);
  } catch (err) {
    next(err);
  }
});

// Template-based invoice
app.post("/api/invoices/:id/pdf", async (req, res, next) => {
  try {
    const invoice = await getInvoiceFromDB(req.params.id);
    if (!invoice) {
      res.status(404).json({ error: "Invoice not found" });
      return;
    }
    const pdf = await df.fromTemplate({
      template: INVOICE_TEMPLATE_ID,
      data: invoice,
      options: { format: "A4", margin: "15mm" },
    });
    res.json(pdf);
  } catch (err) {
    next(err);
  }
});

// Direct download
app.get("/api/invoices/:id/download", async (req, res, next) => {
  try {
    const invoice = await getInvoiceFromDB(req.params.id);
    if (!invoice) {
      res.status(404).json({ error: "Invoice not found" });
      return;
    }
    const pdf = await df.fromTemplate({
      template: INVOICE_TEMPLATE_ID,
      data: invoice,
      output: "base64",
    });
    const buffer = Buffer.from(pdf.data!, "base64");
    res.setHeader("Content-Type", "application/pdf");
    res.setHeader("Content-Disposition", `attachment; filename="invoice-${req.params.id}.pdf"`);
    res.setHeader("Content-Length", buffer.length);
    res.send(buffer);
  } catch (err) {
    next(err);
  }
});

// React-to-PDF
app.post("/api/generate/react", async (req, res, next) => {
  try {
    const { react, data, styles } = req.body;
    if (!react) {
      res.status(400).json({ error: "Missing react field" });
      return;
    }
    const pdf = await df.fromReact({
      react,
      data,
      styles,
      options: { format: "A4", margin: "20mm", printBackground: true },
    });
    res.json(pdf);
  } catch (err) {
    next(err);
  }
});

// Error handling middleware
app.use((err: Error, req: express.Request, res: express.Response, next: express.NextFunction) => {
  if (err instanceof RateLimitError) {
    res.setHeader("Retry-After", String(err.retryAfter));
    res.status(429).json({ error: "Rate limit exceeded", retryAfter: err.retryAfter });
    return;
  }
  if (err instanceof AuthenticationError) {
    res.status(401).json({ error: "Invalid or missing API key" });
    return;
  }
  if (err instanceof ValidationError) {
    res.status(400).json({ error: err.message });
    return;
  }
  if (err instanceof DocuForgeError) {
    res.status(err.statusCode).json({ error: err.message });
    return;
  }
  console.error("Unexpected error:", err);
  res.status(500).json({ error: "Internal server error" });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`PDF service running on port ${PORT}`));

Run it with npx tsx --env-file=.env src/server.ts and you have a fully functional PDF microservice.

Going Further

This tutorial covered the core patterns for Express-based PDF generation. From here, you can extend the service in several directions:

Add authentication middleware to protect your endpoints and pass user context to DocuForge for usage tracking.
Use the batch endpoint (df.batch()) for generating hundreds of PDFs asynchronously through BullMQ.
Deploy as a standalone microservice behind an API gateway, keeping PDF generation isolated from your main application.

For more depth, see the Next.js PDF generation guide for framework-specific patterns, the DocuForge vs Puppeteer comparison for architectural context, and the page layout and styling guide for advanced CSS techniques in PDF rendering.

The Developer's Guide to PDF Page Breaks, Headers, and Footers

Fred T — Mon, 16 Mar 2026 13:00:00 +0000

The Developer's Guide to PDF Page Breaks, Headers, and Footers

If you have ever generated a multi-page PDF from HTML, you already know the pain. A table row splits across two pages. A section heading dangles at the bottom of a page with no content after it. The footer overlaps your body text. Page numbers are nowhere to be found.

Page breaks, headers, and footers are the number one pain point in HTML-to-PDF generation. The web was designed for continuous scrolling, not discrete pages. When you force HTML into a paged medium, you need a different set of CSS properties and rendering strategies than what you use for browser layout.

This guide covers everything you need to control multi-page PDF layout with DocuForge. You will learn the CSS properties that govern page breaks, how to configure repeating headers and footers with page numbers, how to handle tables that span multiple pages, and how to avoid the most common pitfalls. Every technique works with DocuForge's Chromium-based rendering engine, and all code examples use the DocuForge SDK directly.

Page Breaks: The CSS Properties

Chromium supports a set of CSS properties specifically designed for paged media. These are the properties you need to control where pages begin and end in your generated PDFs.

Forcing a Page Break

The break-before and break-after properties insert a page break before or after an element. This is how you force content onto a new page.

<div class="cover-page">
  <h1>Annual Report 2026</h1>
  <p>Acme Corporation</p>
</div>
<!-- Force a new page after the cover -->
<div style="break-after: page;"></div>

<div class="table-of-contents">
  <h2>Table of Contents</h2>
  <!-- ... -->
</div>

A common pattern is to define a reusable utility class:

.page-break {
  break-after: page;
}

Then drop <div class="page-break"></div> anywhere you want a forced break. Simple and predictable.

Preventing a Page Break

The break-inside: avoid property tells Chromium not to split an element across two pages. This is critical for keeping logical units together.

.card {
  break-inside: avoid;
  padding: 16px;
  border: 1px solid #e5e7eb;
  margin-bottom: 12px;
}

When Chromium encounters an element with break-inside: avoid, it will push the entire element to the next page if it does not fit on the current one.

Controlling Text Flow with Orphans and Widows

The orphans and widows properties control how many lines of a paragraph must appear at the bottom or top of a page, respectively. Without these, you get single lines stranded across page breaks.

p {
  orphans: 3;
  widows: 3;
}

This ensures at least three lines of any paragraph appear at the bottom of a page before a break, and at least three lines appear at the top of the next page. Set these globally in your PDF stylesheet to avoid awkward text splits.

Here is a complete example that combines all three techniques:

import DocuForge from "docuforge";

const df = new DocuForge(process.env.DOCUFORGE_API_KEY!);

const result = await df.generate({
  html: `
    <style>
      .page-break { break-after: page; }
      .no-break { break-inside: avoid; }
      p { orphans: 3; widows: 3; }
    </style>
    <div class="no-break">
      <h2>Section One</h2>
      <p>This section stays together on a single page.</p>
    </div>
    <div class="page-break"></div>
    <div class="no-break">
      <h2>Section Two</h2>
      <p>This starts on a new page.</p>
    </div>
  `,
  options: {
    format: "A4",
    margin: { top: "20mm", right: "20mm", bottom: "20mm", left: "20mm" },
  },
});

Keeping Tables Together

Tables are the worst offenders for bad page breaks. Without intervention, Chromium will split a table row across two pages, cutting text in half and making the output unreadable.

Preventing Mid-Row Splits

Apply break-inside: avoid to each table row to prevent Chromium from splitting a row across pages:

tr {
  break-inside: avoid;
}

This works well for tables with short rows. If a single row is taller than the page, Chromium has no choice but to split it, so keep your row content reasonable.

Repeating Table Headers Across Pages

When a table spans multiple pages, readers lose context without column headers. CSS provides a mechanism for this:

thead {
  display: table-header-group;
}

Chromium will repeat the <thead> content at the top of each page where the table continues. This is the single most important CSS rule for long tables in PDFs.

Here is a complete invoice table example:

const invoiceHtml = `
  <style>
    table { width: 100%; border-collapse: collapse; font-family: sans-serif; }
    thead { display: table-header-group; }
    th { background: #1f2937; color: white; padding: 10px; text-align: left; }
    td { padding: 8px 10px; border-bottom: 1px solid #e5e7eb; }
    tr { break-inside: avoid; }
  </style>
  <table>
    <thead>
      <tr>
        <th>Item</th>
        <th>Quantity</th>
        <th>Unit Price</th>
        <th>Total</th>
      </tr>
    </thead>
    <tbody>
      ${lineItems.map(item => `
        <tr>
          <td>${item.name}</td>
          <td>${item.quantity}</td>
          <td>$${item.unitPrice.toFixed(2)}</td>
          <td>$${(item.quantity * item.unitPrice).toFixed(2)}</td>
        </tr>
      `).join("")}
    </tbody>
  </table>
`;

const result = await df.generate({
  html: invoiceHtml,
  options: { format: "A4", margin: "20mm" },
});

Splitting Into Multiple Tables

For very long tables or tables with complex layouts, consider splitting them into separate <table> elements per logical section, each with its own <thead>. This gives you explicit control over where breaks happen and avoids edge cases with Chromium's table-splitting behavior.

Headers via DocuForge Options

DocuForge supports repeating headers on every page of your PDF through the options.header property. This header renders inside the top margin area and supports dynamic page number interpolation.

Basic Header

The header is an HTML string. All styles must be inline because external stylesheets and <style> blocks are not available in the header context.

const result = await df.generate({
  html: "<h1>My Document Content</h1><p>...</p>",
  options: {
    format: "A4",
    margin: { top: "1in", right: "0.5in", bottom: "1in", left: "0.5in" },
    header: `
      <div style="font-size: 10px; color: #6b7280; width: 100%;
                  padding: 0 0.5in; display: flex; justify-content: space-between;">
        <span>Acme Corporation</span>
        <span>Confidential</span>
      </div>
    `,
  },
});

Page Numbers in Headers

Use {{pageNumber}} and {{totalPages}} inside your header HTML. DocuForge interpolates these values for each page during rendering.

header: `
  <div style="font-size: 9px; color: #9ca3af; text-align: right;
              padding: 0 0.5in; width: 100%;">
    Page {{pageNumber}} of {{totalPages}}
  </div>
`,

Header with Logo and Company Name

You can include images in headers using base64-encoded data URIs or publicly accessible URLs:

header: `
  <div style="display: flex; align-items: center; padding: 0 0.5in;
              width: 100%; font-family: sans-serif;">
    <img src="https://example.com/logo.png" style="height: 20px; margin-right: 8px;" />
    <span style="font-size: 11px; font-weight: bold; color: #111827;">Acme Corp</span>
    <span style="margin-left: auto; font-size: 9px; color: #6b7280;">
      Generated on March 7, 2026
    </span>
  </div>
`,

Footers via DocuForge Options

Footers work exactly like headers but render inside the bottom margin area. Use options.footer with the same HTML string approach.

Page X of Y Footer

The most common footer pattern is a centered page counter:

const result = await df.generate({
  html: reportHtml,
  options: {
    format: "Letter",
    margin: { top: "1in", right: "0.75in", bottom: "1in", left: "0.75in" },
    footer: `
      <div style="font-size: 9px; color: #6b7280; text-align: center;
                  width: 100%; padding: 0 0.75in;">
        Page {{pageNumber}} of {{totalPages}}
      </div>
    `,
  },
});

Footer with Multiple Elements

Footers can contain copyright notices, document identifiers, and page numbers together:

footer: `
  <div style="font-size: 8px; color: #9ca3af; width: 100%;
              padding: 0 0.75in; display: flex; justify-content: space-between;
              font-family: sans-serif; border-top: 1px solid #e5e7eb; padding-top: 4px;">
    <span>&copy; 2026 Acme Corporation. All rights reserved.</span>
    <span>DOC-2026-0342</span>
    <span>{{pageNumber}} / {{totalPages}}</span>
  </div>
`,

Keep footer content concise. You have limited vertical space in the margin area, and cramming too much in will cause overlap or clipping.

Margin Configuration for Headers and Footers

This is the most common source of frustration with PDF headers and footers: they render inside the margin area. If your margins are too small, the header or footer will overlap your body content.

Setting Sufficient Margins

When using headers and footers, you need to set margins large enough to contain them. A safe starting point is 1in (roughly 25mm) for the top and bottom margins:

options: {
  format: "A4",
  margin: {
    top: "1in",    // Space for header
    right: "0.5in",
    bottom: "1in", // Space for footer
    left: "0.5in",
  },
  header: `<div style="font-size: 10px; padding: 0 0.5in;">Header text</div>`,
  footer: `<div style="font-size: 10px; padding: 0 0.5in;">Footer text</div>`,
}

What Happens When Margins Are Too Small

If you set margin.top to 10mm but your header content is 15mm tall, the header will overlap the top of your body content. The same applies to footers and margin.bottom. There is no error or warning; the content simply renders on top of itself.

A rule of thumb: measure or estimate the height of your header/footer content, then add at least 5mm of padding. For a simple one-line header at 10px font size, 20mm is usually sufficient. For headers with logos or multiple lines, use 25mm or 1in.

React Component Approach

If you prefer a component-based workflow, the @docuforge/react library provides Document, Page, Header, and Footer components that handle page breaks and positioning for you.

Basic Multi-Page Document

The Page component automatically applies break-after: page between pages. The Footer component is absolutely positioned at the bottom of each page.

import { Document, Page, Header, Footer } from "@docuforge/react";

function AnnualReport({ data }) {
  return (
    <Document>
      <Page size="A4" margin="25mm">
        <Header>
          <div style={{ display: "flex", justifyContent: "space-between",
                        fontSize: "10px", color: "#6b7280" }}>
            <span>Acme Corporation</span>
            <span>Annual Report 2026</span>
          </div>
        </Header>

        <h1 style={{ fontSize: "28px", marginTop: "40px" }}>Annual Report</h1>
        <p>{data.summary}</p>

        <Footer>
          <div style={{ textAlign: "center", fontSize: "9px", color: "#9ca3af" }}>
            Confidential
          </div>
        </Footer>
      </Page>

      <Page size="A4" margin="25mm">
        <Header>
          <div style={{ fontSize: "10px", color: "#6b7280" }}>
            Financial Overview
          </div>
        </Header>

        <h2>Financial Overview</h2>
        <p>{data.financials}</p>

        <Footer>
          <div style={{ textAlign: "center", fontSize: "9px", color: "#9ca3af" }}>
            Page 2
          </div>
        </Footer>
      </Page>
    </Document>
  );
}

Generating the PDF

Pass the React component to df.generate() using the react source:

import DocuForge from "docuforge";

const df = new DocuForge(process.env.DOCUFORGE_API_KEY!);

const result = await df.generate({
  html: renderToString(<AnnualReport data={reportData} />),
  options: {
    format: "A4",
    printBackground: true,
  },
});

The Page component handles break insertion so you do not need to manage break-after: page manually. Each Page is a self-contained unit with its own header, footer, and margin configuration.

Multi-Page Document Patterns

There are three fundamental patterns for structuring multi-page PDFs. Choosing the right one depends on whether your content length is fixed or dynamic.

Pattern 1: Fixed Pages (Certificates, Letters)

When each logical page maps to exactly one physical page, use one Page component (or one <div> with break-after: page) per page. This is typical for certificates, award letters, or form-based documents.

<div class="certificate" style="break-after: page; height: 100%; position: relative;">
  <h1 style="text-align: center; margin-top: 200px;">Certificate of Completion</h1>
  <p style="text-align: center; font-size: 24px;">Awarded to: Jane Smith</p>
  <p style="position: absolute; bottom: 40px; width: 100%; text-align: center;">
    Issued March 7, 2026
  </p>
</div>

<div class="certificate" style="height: 100%; position: relative;">
  <h1 style="text-align: center; margin-top: 200px;">Certificate of Completion</h1>
  <p style="text-align: center; font-size: 24px;">Awarded to: John Doe</p>
  <p style="position: absolute; bottom: 40px; width: 100%; text-align: center;">
    Issued March 7, 2026
  </p>
</div>

Pattern 2: Flowing Content (Reports, Documentation)

When content length is dynamic, let Chromium handle page breaks naturally. Use break-inside: avoid on key elements and set orphans/widows for paragraphs, but do not try to force every break manually.

<style>
  h2 { break-after: avoid; } /* Keep headings with their content */
  .section { break-inside: avoid; }
  p { orphans: 3; widows: 3; }
  table tr { break-inside: avoid; }
  thead { display: table-header-group; }
</style>

<h1>Q1 2026 Performance Report</h1>
<p>Executive summary content that flows naturally across pages...</p>

<h2>Revenue Analysis</h2>
<div class="section">
  <p>Revenue grew 24% year-over-year...</p>
  <table><!-- Long data table --></table>
</div>

<h2>Customer Metrics</h2>
<div class="section">
  <p>Net promoter score reached an all-time high...</p>
</div>

The key rule for flowing content: use break-after: avoid on headings so they never appear stranded at the bottom of a page without the content that follows them.

Pattern 3: Hybrid (Cover + Flowing Content)

Most real-world documents combine fixed and flowing pages. A cover page, a table of contents, and then flowing report content.

const result = await df.generate({
  html: `
    <style>
      .cover { height: 100vh; display: flex; flex-direction: column;
               justify-content: center; align-items: center; break-after: page; }
      .toc { break-after: page; }
      h2 { break-after: avoid; }
      .section { break-inside: avoid; }
      p { orphans: 3; widows: 3; }
    </style>

    <div class="cover">
      <h1>Annual Report 2026</h1>
      <p>Acme Corporation</p>
    </div>

    <div class="toc">
      <h2>Table of Contents</h2>
      <ul>
        <li>Executive Summary ........... 3</li>
        <li>Financial Overview .......... 5</li>
        <li>Product Roadmap ............. 8</li>
      </ul>
    </div>

    <h2>Executive Summary</h2>
    <p>${executiveSummary}</p>

    <h2>Financial Overview</h2>
    <div class="section">${financialContent}</div>
  `,
  options: {
    format: "A4",
    margin: { top: "1in", right: "0.75in", bottom: "1in", left: "0.75in" },
    printBackground: true,
    header: `
      <div style="font-size: 9px; color: #9ca3af; text-align: right;
                  width: 100%; padding: 0 0.75in;">
        Acme Corporation | Annual Report 2026
      </div>
    `,
    footer: `
      <div style="font-size: 9px; color: #9ca3af; text-align: center;
                  width: 100%; padding: 0 0.75in;">
        Page {{pageNumber}} of {{totalPages}}
      </div>
    `,
  },
});

Common Pitfalls and Debugging

These are the issues that trip up nearly every developer working with PDF page layout for the first time.

break-inside: avoid on tall elements creates blank pages. If an element with break-inside: avoid is taller than a single page, Chromium cannot fit it anywhere. It pushes the element to the next page, leaving the current page blank, and then splits it anyway. The fix: only apply break-inside: avoid to elements that you know will fit on a single page. For tall content, let it flow naturally.

Forgetting printBackground: true. By default, Chromium strips background colors and images when generating PDFs. If your design uses background colors for headers, cards, or table rows, you will get a blank white document unless you set printBackground: true in your options.

Using position: fixed for repeating content. In browser rendering, position: fixed pins an element to the viewport. In paged media, it does not repeat on every page. It only appears once, usually on the first page. Use options.header and options.footer for content that must repeat. That is what they are designed for.

Images forcing unexpected page breaks. Large images can push content to the next page if they do not fit. Add max-width: 100% and break-inside: avoid to image containers, and consider setting explicit heights to prevent layout surprises.

External CSS in headers and footers. Stylesheet links and <style> blocks do not work inside options.header and options.footer. All styling must be inline. This is a Chromium limitation, not a DocuForge limitation.

Going Further

This guide covered the core techniques for controlling page layout in HTML-to-PDF generation. For framework-specific implementations, check out these tutorials:

Generate PDFs in Next.js with DocuForge for a complete Next.js integration
Build a Stripe Invoice System for multi-page invoice generation with page numbers
Generate Report PDFs from Supabase Data for data-driven flowing reports
Python PDF Generation with FastAPI for server-side generation in Python

All of these build on the page break, header, and footer techniques covered here. Start with the pattern that matches your use case, and adjust margins and break rules until the output is exactly what you need.

DEV Community: Fred T

Generate PDF Certificates for Your Online Course

Introduction

Step 1: Design the Certificate Template

Step 2: Generate a Single Certificate

Step 3: Build a Verification Endpoint

Step 4: Batch Generate for a Cohort

Step 5: Add a Watermark for Draft Previews

Step 6: Email Certificates

Going Further

Generate Report PDFs from Supabase Data

Generate Report PDFs from Supabase Data

Step 1: Set Up the Project

Step 2: Query Data from Supabase

Step 3: Create a Report Template

Step 4: Generate the Report PDF

Step 5: Store the PDF URL Back in Supabase

Step 6: Automate with Supabase Edge Functions

Step 7: Batch Reports for Multiple Clients

Going Further

How to Add PDF Export to Any React App

Introduction

Approach 1: HTML String Generation

Server API Route

Approach 2: React Component to PDF with fromReact()

Define the PDF Component

{title}

Using @docuforge/react Components

Building a Document

INVOICE

Styling for PDF

The styles Prop

Key Tips

Complete Example: Dashboard Report Export

The PDF Template

{title}

The Dashboard Page

Dashboard

Build an Invoice System with Stripe + DocuForge

Introduction

Architecture Overview

Step 1: Create the Invoice Template

Step 2: Set Up Stripe Webhook Handler

Step 3: Generate the Invoice PDF

Step 4: Email the Invoice

Step 5: Batch Invoices for Monthly Billing

Complete Code

Going Further

Django PDF Generation Made Simple

Introduction

Step 1: Install and Configure

Step 2: Basic PDF Generation View

Step 3: Template-Based Invoice Download

Step 4: Django REST Framework Integration

Step 5: Class-Based View Approach

Step 6: Admin Integration

Going Further

DocuForge vs Puppeteer: Why I Switched

DocuForge vs Puppeteer: Why I Switched

The Puppeteer Setup I Was Running

Problem 1: Memory Leaks and Crashes

Problem 2: Headers, Footers, and Page Breaks

Problem 3: Multi-Language SDKs

The Switch: DocuForge in 10 Minutes

Feature Comparison Table

Performance Comparison

When Puppeteer Still Makes Sense

Conclusion

PDF Generation in Python (FastAPI + DocuForge)

Introduction

Step 1: Install Dependencies

Step 2: Basic HTML-to-PDF Endpoint

Step 3: Template-Based Generation

Step 4: File Download Endpoint

Step 5: Error Handling

Step 6: Running in an Async Context

Complete Application Code

Going Further

How to Generate PDFs in Next.js with DocuForge

How to Generate PDFs in Next.js with DocuForge

The `styles` Prop