HTML to PDF in Convex

// Convex is a full-stack TypeScript backend platform for React and Next.js apps.
// It has three main building blocks:
//   - mutations: transactional writes to the Convex database
//   - queries:   reactive reads that re-run when data changes
//   - actions:   arbitrary async code that can call external APIs
//
// PDF generation fits naturally in an action: actions can make HTTP requests,
// read environment variables, and write results back to the database.
//
// Install the Convex client:
// npm install convex
//
// Authenticate and initialize your project:
// npx convex dev
//
// Set your API key in the Convex dashboard (Settings > Environment Variables):
// PDFPIPE_API_KEY=your_api_key_here

// convex/pdf.ts
// "use node" opts this file into the Node.js runtime.
// Convex actions that call external HTTP APIs require it.

"use node";

import { action } from "./_generated/server";
import { v } from "convex/values";

export const generateInvoicePdf = action({
  args: {
    invoiceId: v.id("invoices"),
    html: v.string(),
  },
  handler: async (ctx, args) => {
    const apiKey = process.env.PDFPIPE_API_KEY;
    if (!apiKey) {
      throw new Error("PDFPIPE_API_KEY is not set");
    }

    const response = await fetch("https://api.pdfpipe.xyz/v1/pdf", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        html: args.html,
        options: { format: "A4" },
        // store: true persists the rendered document and returns a stable URL.
        // Without it the response is a byte stream that cannot be stored in Convex.
        store: true,
        filename: `invoice-${args.invoiceId}.pdf`,
      }),
    });

    if (!response.ok) {
      const err = await response.json().catch(() => ({}));
      const detail = (err as { detail?: string }).detail ?? "render failed";
      throw new Error(`PDF generation failed: ${detail}`);
    }

    const result = await response.json();
    const documentUrl: string = result.document_url;

    // Write the document URL back to the invoices table.
    // ctx.runMutation executes a transactional write from inside an action.
    await ctx.runMutation(internal.pdf.storeDocumentUrl, {
      invoiceId: args.invoiceId,
      documentUrl,
    });

    return { documentUrl };
  },
});

// convex/pdf.ts (continued)
// This internal mutation is called by the action above to persist the URL.
// Internal functions cannot be called from the client — only from other
// Convex functions. That keeps this write operation server-side only.

import { internalMutation } from "./_generated/server";
import { v } from "convex/values";
import { internal } from "./_generated/api";

export const storeDocumentUrl = internalMutation({
  args: {
    invoiceId: v.id("invoices"),
    documentUrl: v.string(),
  },
  handler: async (ctx, args) => {
    await ctx.db.patch(args.invoiceId, {
      documentUrl: args.documentUrl,
      pdfGeneratedAt: Date.now(),
    });
  },
});

// convex/invoices.ts
// When a new invoice is created, schedule the PDF action to run immediately
// in the background. The mutation returns right away; the PDF is generated
// asynchronously without blocking the client.

import { mutation } from "./_generated/server";
import { v } from "convex/values";
import { internal } from "./_generated/api";

export const createInvoice = mutation({
  args: {
    customerId: v.id("customers"),
    html: v.string(),
    amountCents: v.number(),
  },
  handler: async (ctx, args) => {
    const invoiceId = await ctx.db.insert("invoices", {
      customerId: args.customerId,
      amountCents: args.amountCents,
      html: args.html,
      documentUrl: null,
      pdfGeneratedAt: null,
      createdAt: Date.now(),
    });

    // Schedule the PDF action to run after the mutation commits.
    // ctx.scheduler.runAfter(0, ...) fires immediately once the transaction
    // is durable — the 0 ms delay means "as soon as possible".
    await ctx.scheduler.runAfter(0, internal.pdf.generateInvoicePdf, {
      invoiceId,
      html: args.html,
    });

    return invoiceId;
  },
});

// convex/invoices.ts
// You can also schedule PDF generation at a specific time using runAt.
// This is useful for deferred billing documents, scheduled reports,
// or any PDF that should be ready before a known future event.

import { mutation } from "./_generated/server";
import { v } from "convex/values";
import { internal } from "./_generated/api";

export const scheduleMonthlyStatement = mutation({
  args: {
    accountId: v.id("accounts"),
    html: v.string(),
    // Unix timestamp (ms) when the PDF should be generated.
    generateAt: v.number(),
  },
  handler: async (ctx, args) => {
    const statementId = await ctx.db.insert("statements", {
      accountId: args.accountId,
      html: args.html,
      documentUrl: null,
      scheduledFor: args.generateAt,
      createdAt: Date.now(),
    });

    // ctx.scheduler.runAt schedules the action at a specific timestamp.
    // Convex durably persists the schedule — even a server restart will
    // not lose the pending job.
    await ctx.scheduler.runAt(
      args.generateAt,
      internal.pdf.generateInvoicePdf,
      {
        invoiceId: statementId,
        html: args.html,
      }
    );

    return statementId;
  },
});

// convex/invoices.ts
// A reactive query that returns the invoice with its document URL.
// In a React component, useQuery re-renders automatically when the
// document URL is written by the action — no polling needed.

import { query } from "./_generated/server";
import { v } from "convex/values";

export const getInvoice = query({
  args: { invoiceId: v.id("invoices") },
  handler: async (ctx, args) => {
    return await ctx.db.get(args.invoiceId);
  },
});

// app/invoices/[id]/page.tsx
// The React component reads the invoice via useQuery.
// When the background action writes the documentUrl, Convex pushes the
// update over a WebSocket and the component re-renders automatically.

"use client";

import { useQuery } from "convex/react";
import { api } from "@/convex/_generated/api";
import type { Id } from "@/convex/_generated/dataModel";

interface InvoicePageProps {
  params: { id: string };
}

export default function InvoicePage({ params }: InvoicePageProps) {
  const invoice = useQuery(api.invoices.getInvoice, {
    invoiceId: params.id as Id<"invoices">,
  });

  if (invoice === undefined) {
    return <p>Loading...</p>;
  }

  if (invoice === null) {
    return <p>Invoice not found.</p>;
  }

  return (
    <div>
      <h1>Invoice #{invoice._id}</h1>
      <p>Amount: ${(invoice.amountCents / 100).toFixed(2)}</p>

      {invoice.documentUrl ? (
        <a href={invoice.documentUrl} target="_blank" rel="noopener noreferrer">
          Download PDF
        </a>
      ) : (
        // The document URL is null until the background action completes.
        // useQuery updates this automatically — no manual refresh needed.
        <p>Generating PDF...</p>
      )}
    </div>
  );
}

# Set these in the Convex dashboard under Settings > Environment Variables.
# Do NOT use a .env file for Convex actions — process.env in actions reads
# from dashboard-configured variables, not local .env files.

PDFPIPE_API_KEY=your_api_key_here

# For local development, run:
#   npx convex dev
# This starts the local Convex backend and syncs your functions automatically.