@browserless/pdf 10.9.17 → 10.9.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +172 -6
  2. package/package.json +18 -12
package/README.md CHANGED
@@ -1,14 +1,18 @@
1
1
  <div align="center">
2
- <br>
3
2
  <img style="width: 500px; margin:3rem 0 1.5rem;" src="https://github.com/microlinkhq/browserless/raw/master/static/logo-banner.png#gh-light-mode-only" alt="browserless">
4
3
  <img style="width: 500px; margin:3rem 0 1.5rem;" src="https://github.com/microlinkhq/browserless/raw/master/static/logo-banner-light.png#gh-dark-mode-only" alt="browserless">
5
- <br>
6
- <br>
7
- <p align="center"><strong>@browserless/pdf</strong>: Sensible good defaults for exporting a website as PDF.</p>
8
- <p align="center">See our <a href="https://browserless.js.org" target='_blank' rel='noopener noreferrer'>website</a> for more information.</p>
9
- <br>
4
+ <br><br>
5
+ <a href="https://microlink.io"><img src="https://img.shields.io/badge/powered_by-microlink.io-blue?style=flat-square&color=%23EA407B" alt="Powered by microlink.io"></a>
6
+ <img src="https://img.shields.io/github/tag/microlinkhq/browserless.svg?style=flat-square" alt="Last version">
7
+ <a href="https://coveralls.io/github/microlinkhq/browserless"><img src="https://img.shields.io/coveralls/microlinkhq/browserless.svg?style=flat-square" alt="Coverage Status"></a>
8
+ <a href="https://www.npmjs.org/package/browserless"><img src="https://img.shields.io/npm/dm/browserless.svg?style=flat-square" alt="NPM Status"></a>
9
+ <br><br>
10
10
  </div>
11
11
 
12
+ > @browserless/pdf: Sensible good defaults for exporting a website as PDF.
13
+
14
+ See the [pdf section](https://browserless.js.org/#/?id=pdfurl-options) on our website for more information.
15
+
12
16
  ## Install
13
17
 
14
18
  Using npm:
@@ -17,6 +21,168 @@ Using npm:
17
21
  npm install @browserless/pdf --save
18
22
  ```
19
23
 
24
+ ## About
25
+
26
+ 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.
27
+
28
+ ### What this package does
29
+
30
+ The `@browserless/pdf` package allows you to:
31
+
32
+ - **Generate PDFs** from any URL with production-ready defaults
33
+ - **Auto-detect content rendering** using white screenshot detection
34
+ - **Customize margins** with a simple string or per-side configuration
35
+ - **Scale content** to fit pages optimally
36
+ - **Use all Puppeteer PDF options** for advanced customization
37
+
38
+ ### Usage
39
+
40
+ ```js
41
+ const createPdf = require('@browserless/pdf')
42
+ const createGoto = require('@browserless/goto')
43
+
44
+ const goto = createGoto({ timeout: 30000 })
45
+ const pdf = createPdf({ goto })
46
+
47
+ // With browserless
48
+ const browserless = await browser.createContext()
49
+ const pdfBuffer = await browserless.pdf('https://example.com')
50
+
51
+ // Or directly with a page
52
+ const page = await browser.newPage()
53
+ const pdfFn = pdf(page)
54
+ const pdfBuffer = await pdfFn('https://example.com')
55
+ ```
56
+
57
+ ### Default settings
58
+
59
+ The package applies these optimized defaults:
60
+
61
+ | Option | Default | Description |
62
+ |--------|---------|-------------|
63
+ | `margin` | `'0.35cm'` | Page margins (applied to all sides) |
64
+ | `scale` | `0.65` | Content scale factor for optimal fit |
65
+ | `printBackground` | `true` | Include background colors/images |
66
+ | `waitUntil` | `'auto'` | Smart waiting with content detection |
67
+
68
+ ### Options
69
+
70
+ | Option | Type | Default | Description |
71
+ |--------|------|---------|-------------|
72
+ | `margin` | `string \| object` | `'0.35cm'` | Page margins |
73
+ | `scale` | `number` | `0.65` | Scale of the webpage rendering (0.1 - 2) |
74
+ | `printBackground` | `boolean` | `true` | Print background graphics |
75
+ | `waitUntil` | `string` | `'auto'` | When to consider navigation done |
76
+ | `format` | `string` | `'Letter'` | Paper format (A4, Letter, etc.) |
77
+ | `landscape` | `boolean` | `false` | Paper orientation |
78
+ | `width` | `string \| number` | — | Paper width (overrides format) |
79
+ | `height` | `string \| number` | — | Paper height (overrides format) |
80
+ | `pageRanges` | `string` | — | Paper ranges to print, e.g., '1-5, 8' |
81
+ | `headerTemplate` | `string` | — | HTML template for header |
82
+ | `footerTemplate` | `string` | — | HTML template for footer |
83
+ | `displayHeaderFooter` | `boolean` | `false` | Display header and footer |
84
+ | `preferCSSPageSize` | `boolean` | `false` | Give priority to CSS @page size |
85
+
86
+ All [Puppeteer page.pdf() options](https://pptr.dev/api/puppeteer.pdfoptions) are supported.
87
+
88
+ ### Margin configuration
89
+
90
+ Set margins as a single value (applied to all sides) or per-side:
91
+
92
+ ```js
93
+ // Single value for all sides
94
+ await browserless.pdf(url, { margin: '1cm' })
95
+
96
+ // Per-side configuration
97
+ await browserless.pdf(url, {
98
+ margin: {
99
+ top: '2cm',
100
+ right: '1cm',
101
+ bottom: '2cm',
102
+ left: '1cm'
103
+ }
104
+ })
105
+ ```
106
+
107
+ Supported units: `px`, `in`, `cm`, `mm`
108
+
109
+ ### Smart content detection
110
+
111
+ When `waitUntil: 'auto'` (the default), the package:
112
+
113
+ 1. Navigates to the page
114
+ 2. Takes a low-quality screenshot to check for white/blank content
115
+ 3. If the page appears blank, retries until content is detected
116
+ 4. Generates the PDF once content is confirmed
117
+
118
+ This ensures dynamic content (JavaScript-rendered pages) is fully loaded before PDF generation.
119
+
120
+ ```js
121
+ // Use auto detection (default)
122
+ await browserless.pdf(url, { waitUntil: 'auto' })
123
+
124
+ // Or use standard Puppeteer wait conditions
125
+ await browserless.pdf(url, { waitUntil: 'networkidle0' })
126
+ await browserless.pdf(url, { waitUntil: 'domcontentloaded' })
127
+ ```
128
+
129
+ ### Examples
130
+
131
+ #### Basic PDF generation
132
+
133
+ ```js
134
+ const pdfBuffer = await browserless.pdf('https://example.com')
135
+ await fs.writeFile('output.pdf', pdfBuffer)
136
+ ```
137
+
138
+ #### A4 format with custom margins
139
+
140
+ ```js
141
+ const pdfBuffer = await browserless.pdf('https://example.com', {
142
+ format: 'A4',
143
+ margin: '2cm',
144
+ scale: 0.8
145
+ })
146
+ ```
147
+
148
+ #### Landscape with header/footer
149
+
150
+ ```js
151
+ const pdfBuffer = await browserless.pdf('https://example.com', {
152
+ landscape: true,
153
+ displayHeaderFooter: true,
154
+ headerTemplate: '<div style="font-size:10px; text-align:center; width:100%;">Header</div>',
155
+ footerTemplate: '<div style="font-size:10px; text-align:center; width:100%;"><span class="pageNumber"></span>/<span class="totalPages"></span></div>'
156
+ })
157
+ ```
158
+
159
+ #### Print specific pages
160
+
161
+ ```js
162
+ const pdfBuffer = await browserless.pdf('https://example.com', {
163
+ pageRanges: '1-3, 5'
164
+ })
165
+ ```
166
+
167
+ ### How it fits in the monorepo
168
+
169
+ This is a **core functionality package** for PDF generation:
170
+
171
+ | Consumer | Purpose |
172
+ |----------|---------|
173
+ | `browserless` (core) | Provides the `.pdf()` method |
174
+ | `@browserless/cli` | Powers the `browserless pdf` command |
175
+
176
+ ### Dependencies
177
+
178
+ | Package | Purpose |
179
+ |---------|---------|
180
+ | `@browserless/goto` | Page navigation with ad blocking |
181
+ | `@browserless/screenshot` | White screen detection for content verification |
182
+ | `@kikobeats/time-span` | Timing measurements for retry logic |
183
+ | `debug-logfmt` | Structured debug logging |
184
+ | `pretty-ms` | Human-readable time formatting |
185
+
20
186
  ## License
21
187
 
22
188
  **@browserless/pdf** © [Microlink](https://microlink.io), released under the [MIT](https://github.com/microlinkhq/browserless/blob/master/LICENSE.md) License.<br>
package/package.json CHANGED
@@ -1,31 +1,37 @@
1
1
  {
2
2
  "name": "@browserless/pdf",
3
- "description": "Sensible good defaults for exporting a website as PDF",
3
+ "description": "Convert websites to high-quality PDFs with customizable margins, background printing, and optimized scaling.",
4
4
  "homepage": "https://browserless.js.org/#/?id=pdfurl-options",
5
- "version": "10.9.17",
5
+ "version": "10.9.18",
6
6
  "main": "src",
7
+ "author": {
8
+ "email": "hello@microlink.io",
9
+ "name": "microlink.io",
10
+ "url": "https://microlink.io"
11
+ },
7
12
  "repository": {
8
13
  "directory": "packages/pdf",
9
14
  "type": "git",
10
15
  "url": "git+https://github.com/microlinkhq/browserless.git#master"
11
16
  },
12
17
  "bugs": {
13
- "url": "https://github.com/microlinkhq/browserless"
18
+ "url": "https://github.com/microlinkhq/browserless/issues"
14
19
  },
15
20
  "keywords": [
16
- "browser",
17
21
  "browserless",
22
+ "pdf",
23
+ "headless",
18
24
  "chrome",
19
- "chromeless",
25
+ "puppeteer",
20
26
  "export",
21
- "headless",
22
- "media",
23
- "pdf",
24
- "screen"
27
+ "website-to-pdf",
28
+ "print",
29
+ "document",
30
+ "conversion"
25
31
  ],
26
32
  "dependencies": {
27
- "@browserless/goto": "^10.9.16",
28
- "@browserless/screenshot": "^10.9.17",
33
+ "@browserless/goto": "^10.9.18",
34
+ "@browserless/screenshot": "^10.9.18",
29
35
  "@kikobeats/time-span": "~1.0.11",
30
36
  "debug-logfmt": "~1.4.7",
31
37
  "pretty-ms": "~7.0.1"
@@ -41,5 +47,5 @@
41
47
  "test": "exit 0"
42
48
  },
43
49
  "license": "MIT",
44
- "gitHead": "9a7d4769776621dc6cf886698591924049530bb6"
50
+ "gitHead": "f5e8cd0788e4bad3b3ad9b007943754f96653817"
45
51
  }