Short answer: PhantomJS does not have one documented, universal “PDF CSS default.” Its paperSize object controls PDF geometry, while the page’s own CSS, WebKit build, fonts and assets determine most visual details. To reproduce an old PDF in Puppeteer, record the exact PhantomJS job, make page size, margins, media type, colors, fonts and break rules explicit, then compare a fixed fixture.
What PhantomJS actually defaults
PhantomJS documentation describes PDF output through two separate APIs. page.paperSize defines the page dimensions used for PDF rendering; page.render() selects PDF when the output filename has a PDF extension. Do not treat the render method or file extension as a substitute for page geometry.
paperSize controls geometry
- If
paperSizeis omitted, the page determines its size. - Supported dimensions include
mm,cm,inandpx. A unitless value is interpreted as pixels. - Optional margins default to
0. You can provide one margin value or separate top, right, bottom and left values. - Orientation is optional and defaults to portrait.
- Named formats include A3, A4, A5, Legal, Letter and Tabloid.
- Header and footer areas can be configured with heights and callback-generated content.
Therefore, a legacy PDF with a borderless-looking page is not evidence of a hidden PhantomJS CSS reset; zero margins are the documented paperSize default. Unexpected body spacing, heading sizes, list indentation or fonts must be traced to the document CSS, loaded fonts, viewport assumptions or the exact PhantomJS/Qt WebKit build.
Why “PhantomJS CSS defaults” is an unsafe shortcut
The archived API pages do not publish a complete PhantomJS user-agent stylesheet or a universal compatibility reset. Do not copy a guessed body { margin: 8px }, heading scale or font declaration into a migration and call it a PhantomJS default. Inspect the actual legacy HTML and CSS, capture the browser and WebKit versions, and preserve the old PDF as the comparison artifact.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errors#1 Best Overall
How Puppeteer PDF defaults differ
Puppeteer’s page.pdf() API generates the document with the print CSS media type by default. If the old job depended on screen styles, call page.emulateMediaType('screen') before generating the PDF.
Important PDFOptions defaults
| Option | Current documented default | Migration implication |
|---|---|---|
format |
letter |
Set A4, Letter or explicit dimensions instead of relying on the default. |
margin |
Unset (no margins added) | Set each side when matching a known PhantomJS job. |
printBackground |
false |
Set true when the reference contains background graphics. |
preferCSSPageSize |
false |
Content is scaled to fit the API paper size unless CSS page size is preferred. |
scale |
1 |
Unexpected scaling is usually an explicit option or fit-to-paper behavior. |
waitForFonts |
true |
Keep font waiting enabled when comparing line wrapping. |
Puppeteer also modifies colors for printing by default. Use -webkit-print-color-adjust: exact in the relevant print CSS when exact color reproduction is required, and enable printBackground for backgrounds. These controls affect output independently of page margins and size.
Migration procedure: make every visual input explicit
- Freeze the legacy job. Record the PhantomJS version, Qt/WebKit build, viewport, input HTML, stylesheets, image and font URLs, user-agent settings and the complete
paperSizeobject. Keep the original PDF unchanged. - Measure the reference. Note page width and height, orientation, margins, header/footer space, page count, deliberate scaling and representative break locations.
- Translate geometry. Use Puppeteer’s
formatorwidth/height,landscapeandmarginoptions. Choose values that match the old job rather than assuming Letter. - Make CSS explicit. Add
@pagesize and margins, body spacing, font family and weight, line height, colors, backgrounds and page-break rules. This is a compatibility stylesheet for your document, not a claimed PhantomJS reset. - Select media intentionally. Leave Puppeteer’s print media when the old output used print CSS. Use
emulateMediaType('screen')when the legacy render relied on screen rules. - Choose page-size authority. Set
preferCSSPageSize: truewhen the CSS@pagedeclaration must win; otherwise set API dimensions or format and accept fit-to-paper behavior. - Wait for assets. Wait for fonts and any application-specific images or data before calling
page.pdf(). A missing web font can change glyph widths, wrapping and page count. - Compare in a fixed order. Check dimensions and margins first, then page count and break positions, then text wrapping, element coordinates, colors and backgrounds. Add the fixture to regression tests after each intentional adjustment.
Runnable Puppeteer example
This script makes the major decisions visible. Replace the HTML and geometry with the values recorded from your PhantomJS process.
Rank #2
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.setViewport({ width: 1280, height: 900, deviceScaleFactor: 1 });
await page.setContent(`
<!doctype html>
<html>
<head>
<style>
@page { size: A4 portrait; margin: 12mm 10mm 14mm; }
html { -webkit-print-color-adjust: exact; }
body { margin: 0; font-family: Arial, sans-serif; line-height: 1.4; }
h1, h2 { break-after: avoid; }
.keep-together { break-inside: avoid; }
</style>
</head>
<body><h1>Migration fixture</h1><p>Replace this with the legacy HTML.</p></body>
</html>`, { waitUntil: 'networkidle0' });
// Use this line only if the PhantomJS output used screen styles.
// await page.emulateMediaType('screen');
await page.evaluate(() => document.fonts.ready);
await page.pdf({
path: 'reproduced.pdf',
format: 'A4',
landscape: false,
margin: { top: '12mm', right: '10mm', bottom: '14mm', left: '10mm' },
printBackground: true,
preferCSSPageSize: true,
scale: 1,
waitForFonts: true
});
await browser.close();
})();If the old PhantomJS job used a custom width and height, replace format with values such as width: '210mm' and height: '297mm'. Do not specify conflicting geometry casually: with preferCSSPageSize: true, the CSS @page size has priority.
Comparison checklist
- Page dimensions: verify width, height and orientation in physical units.
- Margins and reserved areas: include PhantomJS header/footer space, not just CSS margins.
- Media: confirm whether print or screen rules are active.
- Colors: check both color adjustment and background graphics.
- Fonts: verify that the same files load before capture and that fallback fonts are not used.
- Pagination: compare page count, break positions and orphaned lines.
- Scaling: identify whether content was fitted to paper or rendered at a one-to-one scale.
- Assets: confirm external images, stylesheets and authenticated resources are available.
Common failures and fixes
The new PDF has a different paper size
Cause: Puppeteer’s default is Letter, or CSS and API dimensions disagree. Fix: set format or explicit width/height, then decide whether preferCSSPageSize should be true.
Content is shifted inward or outward
Cause: PhantomJS used explicit margins, CSS @page margins, or a header/footer area that was not recorded. Fix: measure the old PDF and set Puppeteer margins by side; remove accidental body margin with body { margin: 0 } only when the legacy CSS supports that choice.
Colors or backgrounds disappear
Cause: printBackground is false or print color adjustment changes the colors. Fix: set printBackground: true and use -webkit-print-color-adjust: exact where exact colors are part of the requirement.
Line wrapping and page count change
Cause: a different font, font weight, viewport, media type, scale or content width. Fix: wait for document.fonts.ready, verify font responses, set the viewport deliberately, select print or screen media explicitly and compare at scale 1.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →CSS page size is ignored
Cause: preferCSSPageSize remains false, so Puppeteer fits content to the API paper size. Fix: set it to true when @page must control dimensions, or remove the CSS size and control geometry solely through the API.
Only part of the page renders
Cause: the page was captured before asynchronous content, images or fonts finished loading. Fix: use an appropriate navigation wait condition, wait for application readiness and fonts, and ensure protected resources can be fetched by Chromium.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Performance, reliability and version control
PDF reproduction is a controlled comparison, not a promise of pixel identity between engines. Pin the Puppeteer and Chromium versions used in production, and record the exact PhantomJS build for every legacy fixture. A change in browser engine, font file, asset URL or CSS can alter pagination even when the API call is unchanged.
Keep fixtures small enough to diagnose but representative enough to include long paragraphs, headings, lists, images, backgrounds, custom fonts and deliberate page breaks. Compare machine-readable properties such as page dimensions and count where your PDF tooling permits, then inspect rendered pages for wrapping and color differences. Treat every adjustment as a documented compatibility decision.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Best Value
- Used Book in Good Condition
Or skip the browser setup
For a direct URL-to-PDF or screenshot workflow, ScreenshotNeo provides a single API endpoint and also supports PDF output. Its cleanup steps accept cookie or consent banners and remove more than 60 known consent platforms, newsletter popups and chat widgets before capture; each step can be disabled. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients.
Use the ScreenshotNeo documentation for request options. A PDF request can be made with the same endpoint:
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://stripe.com
-d format=pdf
-o document.pdfThe service also accepts explicit paper size, margins, landscape mode and page ranges, so you can keep those values close to the legacy job’s recorded geometry. Every plan includes the feature set. The Free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots.
Create a free ScreenshotNeo account to try the 1,000 monthly shots without entering a card.
Recommended Free Tools
Equivalent ScreenshotNeo calls in Python and Node.js
Python
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const fs = require('node:fs');
fs.writeFileSync('shot.webp', Buffer.from(await res.arrayBuffer()));Frequently Asked Questions
Does PhantomJS always add an 8px body margin to PDFs?
No. The documented PDF margin default belongs to paperSize and is zero when omitted. Body spacing must be verified in the actual HTML, CSS and PhantomJS WebKit build.
Should I use format or CSS @page in Puppeteer?
Use one deliberate source of truth. Set preferCSSPageSize: true when CSS should win; otherwise set the API format or dimensions and allow Puppeteer to fit content to that paper.
Can Puppeteer guarantee a pixel-identical replacement for PhantomJS?
No. Different browser engines, fonts, CSS support and pagination behavior can produce differences. Use pinned versions and fixture-based comparisons to control the migration.
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.
Free tools Windows power users keep installed
One-click scans. No signup required.
