Next.js PDF Generation: Reliable Reports, Invoices & Downloads

Define what makes a generated document correct

Invoices, statements, certificates, and reports become durable records outside the application. A successful PDF response says little about whether totals are accurate, private fields are protected, text is readable, or the document can be reproduced later. Define a contract for content, layout, language, accessibility, retention, and authorization before choosing a renderer.

Choose browser-based HTML rendering when existing print layouts matter, or a programmatic PDF library when deterministic drawing and document structure are central. Evaluate the actual deployment runtime and document requirements with representative samples.

Render an immutable snapshot with a versioned template

Gather authorized data into a validated snapshot before rendering. A worker that queries mutable records throughout a long report can combine values from different moments. Capture the business record version, calculations, locale, zone, template version, and source references needed to explain the output.

For issued invoices or certificates, define whether later corrections create a replacement version rather than changing an existing file. Use the concurrency controls in our version-check guide when snapshot creation must correspond to a particular record revision.

Use explicit rounding and date policies. Keep display formatting separate from authoritative amounts and timestamps, and avoid recalculating business values from rendered strings.

Move expensive rendering into bounded background work

A short, small document may fit a synchronous request budget. Large reports and browser-based rendering usually benefit from a durable job that survives a browser disconnect. Return an operation ID, expose an authorized status endpoint, and let the user retrieve the result when ready.

requested → snapshot_ready → queued → rendering
          → verifying → available → expired

Record: tenant, requester, source revision,
template version, attempts, artifact checksum,
safe error code, creation time, expiry

Limit renderer concurrency, memory, pages, input bytes, and total duration. Use leases and retry limits, and deduplicate by the business document version plus template and locale when reuse is appropriate. Our background-work guide covers durable dispatch and recovery.

Render trusted templates with constrained resource access

Keep templates under application control and escape untrusted values for their output context. Avoid letting customers supply arbitrary HTML, scripts, file paths, or URLs to a privileged renderer. A headless browser can access network resources unless the application and environment restrict it.

Serve required images, styles, and fonts from approved sources or bundle them with the worker. Deny unnecessary outbound access and local file access, isolate each job, and remove temporary data after completion. Use fresh browser contexts when sharing a process so cookies and cached private content do not cross tenant boundaries.

Keep rendering credentials narrowly scoped. The worker should receive the approved snapshot rather than broad production database authority whenever the architecture permits it.

Make pagination and asset readiness explicit

Design print layouts with realistic long names, long descriptions, multiple currencies, empty sections, and hundreds of table rows. Specify how repeated table headings, page numbers, totals, and signatures behave across page breaks. Avoid fixed heights that hide overflow.

Wait for required fonts and images using deterministic readiness checks before capture. Set a timeout and fail with a meaningful job reason when an essential asset is missing. Bundle fonts with the required glyph coverage and licensing so deployment machines produce predictable text.

Provide selectable text, meaningful document metadata, and an accessible reading order where the renderer supports it. If tagged PDF accessibility is required, verify that capability in the chosen tool and output; visual similarity alone is insufficient.

Publish artifacts only after verification and authorization

Write completed files to private storage with random object keys, encryption, and an appropriate retention window. Record byte size and checksum. Mark the document available only after storage and verification succeed; a worker crash should not expose a partial artifact.

The download route must resolve the user and tenant again, check access to the source document and requested version, and then stream the file or issue a short-lived signed link. Configure the response filename and content type safely. Avoid putting permanent private URLs into email, browser analytics, or public caches.

A completed job does not guarantee that its original requester still has permission. Membership changes and revoked access must also affect retrieval.

Check both business content and rendered pages

Validate document totals and required fields against the snapshot, check page count and output size, extract representative text, and render pages to images for layout review. A parseable PDF can still contain clipped tables, blank pages, missing glyphs, or an unreadable footer.

Maintain fixtures for long text, non-Latin scripts, right-to-left content where supported, large tables, missing images, and different locales. Run visual checks after template, font, renderer, or runtime changes. Compare expected structure and meaningful regions rather than relying solely on a byte-for-byte match that metadata can change.

Track generation latency and explain failed jobs

Measure queue age, render duration, memory pressure, verification failures, artifact size, retries, and download outcomes by template version. Log operation IDs and safe errors rather than document bodies or signed links.

Classify permanent data errors separately from temporary asset or storage outages. Retry with bounded backoff, preserve the immutable snapshot, and avoid generating a new business identifier on every attempt. Test worker termination during render, lost upload acknowledgments, duplicate dispatch, expired links, and permission revocation.

For documents containing personal data, connect artifact expiry to the policies in our privacy workflow guide.

Next.js PDF generation checklist