Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Improve large-document PDF output by controlling print layout first, then making Puppeteer wait for the page’s actual content and validating the generated PDF at production scale. Page.pdf() uses print media, so a polished screen view does not guarantee a good PDF. Set page size and margins deliberately, choose whether CSS @page or Puppeteer options control geometry, enable backgrounds when needed, and measure real documents rather than relying on an assumed page or memory limit.
Why a PDF can look different from the browser page
Puppeteer’s Page.pdf() renders using the print media type. That means @media print rules, print visibility, page-break behavior, and print-specific typography affect the output. Screen-mode inspection alone will miss problems that appear only during PDF generation. See the Puppeteer Page.pdf() API reference and its PDF generation guide.
Start by treating the PDF as a print layout with a defined sheet size—not as a screenshot of a long web page. Decide which layer owns the page dimensions, ensure fonts and application-generated content are ready, and inspect representative pages at the beginning, middle, and end of long output.
Control page size, margins, and scaling
Puppeteer can receive paper settings through format, width, or height, and CSS can declare a page using @page. The preferCSSPageSize option decides whether CSS page dimensions take precedence over those Puppeteer paper options. Its default is false; in that mode, content is scaled to fit the selected paper size. If exact geometry matters, select the authority explicitly instead of letting a mismatch trigger unexpected scaling.
#1 Best Overall
- Used Book in Good Condition
- Use CSS
@pagewithpreferCSSPageSize: truewhen the document stylesheet should own its paper dimensions and margins. - Use Puppeteer’s
formator explicitwidth/heightwhen the calling code should own the page size. Keep CSS page dimensions compatible with that choice. - Set the
scaledeliberately. Puppeteer documents a supported range of 0.1 to 2, with a default of 1; changing scale affects the fit and apparent size of all content.
For example, a report designed for A4 should not accidentally declare Letter in CSS while the Node code selects A4 with CSS priority disabled. Compare the resulting dimensions and content scale against the intended output rather than assuming the browser has honored the stylesheet.
Make print CSS and colors intentional
Keep a print-specific stylesheet for elements that should differ on paper: navigation and interactive controls can be hidden, links and headings can be restyled, and page-break rules can prevent a heading or table row from splitting badly. Check the behavior in the actual generated PDF because browser print pagination is part of the output.
Background printing is off by default. If charts, colored panels, or other essential design elements depend on background fills, set printBackground: true. Puppeteer also notes that PDF colors are modified for printing by default; CSS -webkit-print-color-adjust: exact can request exact color rendering where the design requires it. Validate the resulting file, since exact colors and background coverage may increase output size or render work depending on the document.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallWait for the document you intend to print
Puppeteer waits for document.fonts.ready by default before producing a PDF. That helps with web fonts, but it does not mean every application-specific operation is complete. Data fetching, chart drawing, lazy images, client-side pagination, and image decoding may need separate readiness checks.
Rank #2
The PDF guide demonstrates navigation with waitUntil: 'networkidle2', but network quiet is only a navigation strategy, not proof that your app’s content is ready. A page can render data after a request has finished, or keep background requests open indefinitely. Prefer an application-owned readiness marker when you can add one, and wait for the particular element or state that means the printable content is complete.
Runnable Puppeteer example for a long report
This Node.js example uses CSS page dimensions as the authority, waits for navigation and a report-ready marker, and writes the resulting PDF bytes to disk. Replace the URL and readiness selector with those for your application. Add the marker only after data, charts, and images needed in the report are ready.
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({ headless: true });
try {
const page = await browser.newPage();
await page.goto('https://example.com/report', {
waitUntil: 'networkidle2',
timeout: 60000,
});
// Replace this with a selector your application sets when the report is ready.
await page.waitForSelector('[data-report-ready="true"]', {
timeout: 30000,
});
await page.emulateMediaType('print');
const pdf = await page.pdf({
path: 'report.pdf',
preferCSSPageSize: true,
printBackground: true,
scale: 1,
displayHeaderFooter: false,
timeout: 120000,
});
console.log(`Wrote ${pdf.length} bytes to report.pdf`);
} finally {
await browser.close();
}
})();The example assumes the page includes print CSS and an @page rule. If you instead want Puppeteer to control paper size, provide format (for example, 'A4') or explicit dimensions and leave preferCSSPageSize off. Do not combine conflicting dimensions without checking whether the content is being scaled.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →The documented Page.pdf() result is a Uint8Array. The timeout shown is a caller-side limit for the operation, not a promise that every document will finish within that duration.
Large-document quality and reliability checklist
- Geometry: Confirm one source owns paper size and margins; inspect scaling, clipping, and unexpected blank pages.
- Pagination: Review page breaks around headings, tables, images, and sections that should stay together.
- Content readiness: Verify fonts, app data, charts, and images are ready before PDF generation.
- Visual fidelity: Check background colors, text rendering, links, and print-only visibility in the actual PDF.
- Representative load: Test documents with production-like content and length, not only a short fixture.
- Operations: Record render duration, browser process memory, output size, correctness, and failure rate for each run.
The reviewed Puppeteer documentation does not establish a universal maximum page count, DOM size, PDF size, or memory ceiling. Therefore, set capacity expectations from measurements on your own representative workload. If a document exceeds the practical bounds of your service, application-level partitioning may be worth evaluating, but validate cross-document page breaks, numbering, headers, and references before adopting it; the documentation does not provide a universal split threshold.
When streaming PDF bytes helps—and what it does not promise
Page.createPDFStream() returns a ReadableStream<Uint8Array>, whereas Page.pdf() returns a Uint8Array. A stream can fit a consumer or file pipeline that processes bytes incrementally. It changes how your application receives generated bytes; the API documentation does not say that Chrome lays out or renders the document in smaller chunks, uses less render memory, or avoids browser memory exhaustion. Measure the full pipeline before treating streaming as a resource fix. See the stream API reference.
Choose and pin the browser mode you test
Puppeteer documents standard headless Chrome and chrome-headless-shell. The shell may be more performant for automation tasks where its reduced compatibility is acceptable, but that is not a documented promise of better PDF fidelity. Test the exact mode and browser version used in production against the documents that matter. The headless modes guide describes the trade-off.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Puppeteer’s supported browsers table is version-sensitive. The reference currently identifies Puppeteer 25.12.0 with Chrome for Testing 154.0.8037.57; check the table for the package version actually installed rather than treating that mapping as permanent. The documentation says Puppeteer downloads Chrome for Testing from v20 onward. Record the Puppeteer version, browser version, and headless mode with your PDF test results so visual changes can be traced to an environment change.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Common PDF problems and practical fixes
Content is unexpectedly small or leaves excessive whitespace
Check whether CSS @page dimensions conflict with the Puppeteer format or dimensions. With preferCSSPageSize: false, CSS content is scaled to fit the selected paper size. Choose the intended page-size authority and inspect the result at scale 1 before adjusting scale to compensate.
Backgrounds or chart colors are missing
Set printBackground: true when printed backgrounds are required. If colors still differ from the screen, inspect print CSS and consider -webkit-print-color-adjust: exact on the relevant elements. Test the saved PDF, not only the browser’s screen rendering.
Fonts, charts, or images are absent or substituted
Wait for the application’s actual ready state in addition to navigation. Puppeteer’s font-ready wait does not cover every chart, data request, image decode, or lazy-loading workflow. Use explicit selectors or application signals, and make sure lazy images in later pages have been loaded before generating the PDF.
Free tools Windows power users keep installed
One-click scans. No signup required.
The output has bad page breaks or clipped content
Review print styles and page-break rules, then inspect representative pages throughout the document. Large tables and long unbroken content can expose layout problems not visible in a short sample. Adjust the document’s print layout rather than assuming a different headless mode will fix pagination.
Best Value
The run times out or the browser runs out of memory
First separate a readiness timeout from a PDF-generation failure: log navigation, app-ready waiting, and PDF creation as distinct stages. Reduce unnecessary page content and resources where possible, measure memory and render time, and test with realistic input. A longer timeout can accommodate a slow render but does not increase available memory or guarantee success. The official references reviewed specify no universal document-size limit.
A streamed result does not prevent memory pressure
Streaming can reduce how much generated output your application must hold at once, depending on the consumer pipeline, but it is not documented to reduce Chrome’s layout or render memory. Compare measured process memory for the complete workflow and use another architectural change if rendering is the bottleneck.
Or skip the browser setup
If your need is to capture a URL as a PDF rather than tune Puppeteer’s rendering pipeline, ScreenshotNeo is a website screenshot API and MCP server with PDF output. It is a separate URL-to-PDF option, not a replacement for the print-CSS controls above. The API also supports PNG, JPEG, and WebP output. Use its documented parameters and options at ScreenshotNeo documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.pdfUse the PDF output option documented by ScreenshotNeo for PDF captures. Its clean-shot handling removes cookie/consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are not billed. Its MCP server lets AI agents take screenshots, and the Free plan includes 1,000 shots monthly with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.
FAQ
Does Puppeteer set a maximum PDF page count?
The cited Puppeteer API and guide pages do not specify a universal maximum page count. Practical capacity depends on the document and runtime environment, so measure your workload.
Does using chrome-headless-shell guarantee a faster or more accurate PDF?
No. Puppeteer describes it as potentially more performant for some automation tasks and notes reduced compatibility; it does not promise improved PDF fidelity. Benchmark and visually validate the precise setup you plan to deploy.
Which Puppeteer API is best for writing a PDF file?
Use Page.pdf() for its documented Uint8Array result and use Page.createPDFStream() when a stream-based byte consumer better fits your application. Neither return type alone determines Chrome’s rendering resource use.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
