Server PDF (Playwright)

When to use

Always keep client fallback when server feature is disabled or unavailable.

Install (server host only)

npm install playwright
npx playwright install chromium

Heavy — gate behind env flag; not suitable for Edge runtime.

Feature flag

ENABLE_SERVER_PDF=true

export function isServerPdfEnabled(): boolean {
  return process.env.ENABLE_SERVER_PDF === "true";
}

Route handler

// app/api/generate-pdf/route.ts
export const runtime = "nodejs";

export async function POST(req: Request) {
  if (!isServerPdfEnabled()) {
    return Response.json({ error: "Server PDF disabled" }, { status: 503 });
  }
  const { html, filename } = schema.parse(await req.json());
  const pdf = await renderHtmlToPdf(html);
  return new Response(pdf, {
    headers: {
      "Content-Type": "application/pdf",
      "Content-Disposition": `attachment; filename="${filename}"`,
    },
  });
}

Render helper

import { chromium } from "playwright";

export async function renderHtmlToPdf(html: string): Promise<Buffer> {
  const browser = await chromium.launch({ headless: true });
  try {
    const page = await browser.newPage();
    await page.setContent(html, { waitUntil: "networkidle" });
    return await page.pdf({ format: "A4", printBackground: true });
  } finally {
    await browser.close();
  }
}

Reuse browser instance in production with connection pooling if volume is high.

Client flow

1. Try POST /api/generate-pdf with sanitized HTML snapshot
2. On 503/500 → fall back to client jsPDF (see client-document-export skill)
3. Rate-limit API (5/min per IP)

Security

• Never pass raw user HTML without sanitization if untrusted
• Prefer server-rendered template from structured JSON data
• Cap HTML size and generation timeout
• Don't expose Playwright on Edge — runtime = "nodejs" only

Deployment notes

• Vercel serverless: Playwright often not available — use dedicated Node host or external PDF service
• Docker: install Chromium deps in image
• Cold start: expect 2–5s first request

Anti-patterns

• Mandatory server PDF with no client fallback
• Running Playwright on every request without pool/timeout
• Sending full dashboard DOM HTML with script tags from client

Pair with: client-document-export, resend-email-nextjs, nextjs-api-routes.