Convert websites to high-quality PDFs with customizable margins, background printing, and optimized scaling.
npm install @browserless/pdf> @browserless/pdf: Sensible good defaults for exporting a website as PDF.
See the pdf section on our website for more information.
Using npm:
``sh`
npm install @browserless/pdf --save
This package provides PDF generation from web pages with sensible defaults and smart content detection. It wraps Puppeteer's page.pdf() with optimized settings and a retry mechanism to ensure the page is fully rendered before generating the PDF.
The @browserless/pdf package allows you to:
- Generate PDFs from any URL with production-ready defaults
- Auto-detect content rendering using white screenshot detection
- Customize margins with a simple string or per-side configuration
- Scale content to fit pages optimally
- Use all Puppeteer PDF options for advanced customization
`js
const createPdf = require('@browserless/pdf')
const createGoto = require('@browserless/goto')
const goto = createGoto({ timeout: 30000 })
const pdf = createPdf({ goto })
// With browserless
const browserless = await browser.createContext()
const pdfBuffer = await browserless.pdf('https://example.com')
// Or directly with a page
const page = await browser.newPage()
const pdfFn = pdf(page)
const pdfBuffer = await pdfFn('https://example.com')
`
The package applies these optimized defaults:
| Option | Default | Description |
|--------|---------|-------------|
| margin | '0.35cm' | Page margins (applied to all sides) |scale
| | 0.65 | Content scale factor for optimal fit |printBackground
| | true | Include background colors/images |waitUntil
| | 'auto' | Smart waiting with content detection |
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| margin | string \| object | '0.35cm' | Page margins |scale
| | number | 0.65 | Scale of the webpage rendering (0.1 - 2) |printBackground
| | boolean | true | Print background graphics |waitUntil
| | string | 'auto' | When to consider navigation done |format
| | string | 'Letter' | Paper format (A4, Letter, etc.) |landscape
| | boolean | false | Paper orientation |width
| | string \| number | — | Paper width (overrides format) |height
| | string \| number | — | Paper height (overrides format) |pageRanges
| | string | — | Paper ranges to print, e.g., '1-5, 8' |headerTemplate
| | string | — | HTML template for header |footerTemplate
| | string | — | HTML template for footer |displayHeaderFooter
| | boolean | false | Display header and footer |preferCSSPageSize
| | boolean | false | Give priority to CSS @page size |
All Puppeteer page.pdf() options are supported.
Set margins as a single value (applied to all sides) or per-side:
`js
// Single value for all sides
await browserless.pdf(url, { margin: '1cm' })
// Per-side configuration
await browserless.pdf(url, {
margin: {
top: '2cm',
right: '1cm',
bottom: '2cm',
left: '1cm'
}
})
`
Supported units: px, in, cm, mm
When waitUntil: 'auto' (the default), the package:
1. Navigates to the page
2. Takes a low-quality screenshot to check for white/blank content
3. If the page appears blank, retries until content is detected
4. Generates the PDF once content is confirmed
This ensures dynamic content (JavaScript-rendered pages) is fully loaded before PDF generation.
`js
// Use auto detection (default)
await browserless.pdf(url, { waitUntil: 'auto' })
// Or use standard Puppeteer wait conditions
await browserless.pdf(url, { waitUntil: 'networkidle0' })
await browserless.pdf(url, { waitUntil: 'domcontentloaded' })
`
#### Basic PDF generation
`js`
const pdfBuffer = await browserless.pdf('https://example.com')
await fs.writeFile('output.pdf', pdfBuffer)
#### A4 format with custom margins
`js`
const pdfBuffer = await browserless.pdf('https://example.com', {
format: 'A4',
margin: '2cm',
scale: 0.8
})
#### Landscape with header/footer
`js`
const pdfBuffer = await browserless.pdf('https://example.com', {
landscape: true,
displayHeaderFooter: true,
headerTemplate: 'Header',
footerTemplate: '/'
})
#### Print specific pages
`js`
const pdfBuffer = await browserless.pdf('https://example.com', {
pageRanges: '1-3, 5'
})
This is a core functionality package for PDF generation:
| Consumer | Purpose |
|----------|---------|
| browserless (core) | Provides the .pdf() method |@browserless/cli
| | Powers the browserless pdf command |
| Package | Purpose |
|---------|---------|
| @browserless/goto | Page navigation with ad blocking |@browserless/screenshot
| | White screen detection for content verification |@kikobeats/time-span
| | Timing measurements for retry logic |debug-logfmt
| | Structured debug logging |pretty-ms` | Human-readable time formatting |
|
@browserless/pdf © Microlink, released under the MIT License.
Authored and maintained by Microlink with help from contributors.
The logo has been designed by xinh studio.
> microlink.io · GitHub microlinkhq · X @microlinkhq