Building Pdf Generator Service

We've all been there. A stakeholder asks for a "simple PDF export" for a report, an invoice, or a receipt. You reach for a library, write a few lines of code, and ship it. Two weeks later, the service is leaking memory, the rendering looks different on staging versus production, and your P99 latency has spiked because the process is blocking the event loop.

PDF generation is one of the most deceptively difficult problems in backend engineering. It sits at the intersection of strict binary formats, complex CSS rendering engines, and resource-intensive I/O. When you try to solve it with naive approaches, you quickly run into a wall of edge cases: missing fonts, truncated text, memory exhaustion from unclosed browser instances, and layout shifts that break legal compliance for financial documents.

The core issue is that most engineers treat PDF generation as a text-processing problem. It isn't. It's a rendering problem. You need a full browser engine to interpret CSS, calculate layouts, and handle print media queries correctly. But spinning up a browser engine for every request is expensive. Managing the lifecycle of that engine is hard. And doing it at scale without crashing your workers requires deliberate architectural choices.

We built this skill so you don't have to reinvent the wheel. Instead of spending sprints fighting rendering quirks, you get a production-grade, async PDF service that handles the complexity for you. It's designed for engineers who need reliable, scalable document generation without the operational overhead.

The Hidden Tax of "Just Use a Library"

When you ignore the complexity of PDF generation, the cost isn't just in development time; it's in operational stability and trust. We see teams adopt quick-and-dirty solutions and pay for them later in three specific ways.

First, there's the memory tax. Headless browsers are heavy. If you spawn a new Chrome process for every PDF request and don't manage the lifecycle rigorously, you'll hit memory limits within hours. A single leaked context or an unclosed page can consume hundreds of megabytes. In a high-throughput environment, this leads to OOM kills, service restarts, and cascading failures. The scalability challenges of headless browser tasks are well-documented, and without proper orchestration, your service will grind to a halt under load ^[1].

Second, there's the consistency tax. Rendering engines vary. A PDF that looks perfect on your local Mac might render with broken fonts or shifted elements on a Linux server. This is especially critical for regulated industries like fintech or healthcare, where document formatting is part of the compliance requirements. If your invoices or reports look different depending on the server, you've lost trust with your customers.

Third, there's the vendor lock-in tax. Some teams solve this by offloading PDF generation to third-party APIs. This works until you hit rate limits, face unexpected per-page pricing, or need to pass sensitive data through an external endpoint. For data-sensitive workflows, keeping PDF generation in-house is often a security requirement, not just a cost optimization.

The alternative is to build a robust, self-hosted service. But building one that handles async rendering, browser lifecycle management, and error recovery is non-trivial. That's where we step in.

The Invoice Pipeline That Cost Us Three Days

Imagine a mid-sized logistics company that needed to automate invoice generation. They started with a simple Python library that converted HTML to PDF. It worked fine for basic text. But when the design team added complex CSS grids, background images, and print-specific styles, the library fell apart. Text was truncated, colors were wrong, and the layout collapsed on A4 pages.

The team pivoted to a headless Chrome approach. They wrote a script that launched Chrome, navigated to a template, and saved the PDF. It worked locally. But in production, the service started crashing. They weren't managing the browser lifecycle. Each request spawned a new process, and over time, the server ran out of file descriptors and memory. They spent three days debugging race conditions and memory leaks before realizing they needed a proper service architecture.

This is a common pattern. The technical approach of using Python with Chrome's headless mode is powerful, but it requires careful implementation to handle the browser instance and template rendering correctly ^[3]. The CSS tricks needed for print-optimized layouts also need to be handled explicitly, as standard web CSS doesn't always translate to print media queries ^[7].

The turning point came when they stopped treating PDF generation as a script and started treating it as a service. They implemented a FastAPI endpoint with Playwright, managed the browser pool, and containerized the environment. Suddenly, the crashes stopped. The rendering became consistent. And they could scale horizontally without worrying about process management.

A Self-Hosted, Async PDF Engine

Once you install this skill, you're no longer writing scripts. You're deploying a scalable PDF generation service that integrates seamlessly into your existing infrastructure. Here's what changes.

You get an async FastAPI service that leverages Playwright for rendering. This means your PDF generation doesn't block the event loop. You can handle multiple concurrent requests without spawning a new browser instance for each one. The service manages the browser lifecycle internally, reusing contexts and pages efficiently to minimize memory usage.

The architecture is designed for production. We use a multi-stage Dockerfile that installs only the necessary dependencies, runs playwright install --with-deps --no-shell to optimize the image size, and configures a non-root user for security. This ensures your service is lightweight and secure from the moment it starts.

Rendering is consistent across environments. Because the service runs in a container with pinned dependencies and a specific browser version, your PDFs look the same on your laptop, in CI, and in production. We include canonical references for Playwright's PDF export parameters and headless configuration, so you have the official documentation at your fingertips ^[6].

The service supports A4 and Letter formats, handles CSS print media queries, and includes robust error handling. If a template fails to render, the service returns a clear error response instead of crashing. You can also integrate this service with other tools. For example, if you're building an invoice system, this PDF service pairs perfectly with building-invoice-generator to handle the document layout. If you need to generate QR codes for receipts, you can use building-qr-code-generator to embed them dynamically.

For teams deploying to AWS, this architecture is compatible with Lambda, though you'll need to manage the container image size carefully. The principles of running headless Chrome on serverless platforms are well-established, and this service provides a solid foundation for that approach ^[4].

We also ensure the service is documented and validated. You get a validator script that checks file existence, runs ruff linting, and validates the Dockerfile syntax. This catches issues before they reach production. And if you need to document the API endpoints, you can use api-documentation-pack to generate interactive docs automatically.

The result is a service that just works. You send HTML, you get PDF. No memory leaks, no inconsistent rendering, no vendor lock-in.

What's in the Pack

This isn't a single script. It's a complete, multi-file deliverable that gives you everything you need to deploy and maintain a production PDF service.

• skill.md — Orchestrator skill definition. Explicitly references all relative paths for templates, references, scripts, validators, and examples. Defines architecture, agent workflows, and usage patterns for the PDF service.
• templates/service.py — Production-grade FastAPI + Playwright service. Implements async PDF generation from HTML/CSS templates, manages browser lifecycle, supports A4/Letter formats, and includes robust error handling for headless Chrome.
• templates/Dockerfile — Multi-stage production Docker image. Installs Python deps, runs playwright install --with-deps --no-shell to optimize size, configures non-root user, and exposes port 8000.
• templates/requirements.txt — Pin production dependencies: fastapi, uvicorn, playwright, jinja2, pydantic, and async-safe browser management.
• references/playwright-pdf-export.md — Canonical Playwright PDF export documentation. Covers page.pdf() parameters, format options, -webkit-print-color-adjust property, and async/sync API patterns from official docs.
• references/headless-configuration.md — Canonical Playwright headless mode docs. Covers new Chromium headless channel: 'chromium', headless: false for debugging, slowMo for tracing, and MCP configuration.
• scripts/setup.sh — Executable scaffolding script. Creates project structure, installs Python deps, runs playwright install --with-deps --no-shell, and sets up git hooks.
• validators/validate.sh — Project validator. Checks file existence, runs ruff linting, validates Dockerfile syntax, and exits non-zero on any failure or missing dependency.
• examples/invoice.html — Worked example HTML/CSS invoice template. Uses standard web layout, print-optimized CSS, and placeholder data for testing the PDF generator.
• examples/test_client.py — Worked example async client. Demonstrates how to call the service, handle PDF streams, and verify output integrity locally.

Ship Your First PDF

Stop fighting with rendering libraries and memory leaks. Start shipping reliable, scalable PDF generation.

Upgrade to Pro to install this skill. Once installed, run scripts/setup.sh to scaffold your project, review the examples, and deploy the service. You'll have a production-ready PDF engine in minutes, not weeks.

If you're also designing the API endpoints, follow the patterns in api-design-pack to ensure your service is consistent and maintainable. And if you need to generate client SDKs for your frontend team, use building-rest-api-sdk-generator to automate that process.

The PDF generation problem is solved. All that's left is to install it.