@zinejs/pdf 0.8.2 → 0.9.0
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.
- package/README.md +32 -84
- package/dist/index.js +20 -15
- package/dist/index.js.map +1 -1
- package/dist/index.umd.js +2 -2
- package/dist/index.umd.js.map +1 -1
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# @zinejs/pdf
|
|
2
2
|
|
|
3
|
-
PDF content source for [zinejs](https://
|
|
3
|
+
PDF content source for [zinejs](https://zinejs.com/docs/), powered by [pdf.js](https://mozilla.github.io/pdf.js/). Renders PDF pages to canvases that [`@zinejs/core`](https://www.npmjs.com/package/@zinejs/core) paints as a flipbook.
|
|
4
|
+
|
|
5
|
+
> **Docs and examples:** [zinejs.com/docs](https://zinejs.com/docs/) · [CDN example](https://zinejs.com/examples/html-cdn)
|
|
4
6
|
|
|
5
7
|
## Install
|
|
6
8
|
|
|
@@ -8,118 +10,64 @@ PDF content source for [zinejs](https://github.com/), powered by [pdf.js](https:
|
|
|
8
10
|
npm install @zinejs/core @zinejs/pdf
|
|
9
11
|
```
|
|
10
12
|
|
|
11
|
-
`pdfjs-dist`
|
|
13
|
+
`pdfjs-dist` installs with this package. It is loaded lazily (dynamic `import`) so it never lands in the `@zinejs/core` bundle. If your app already depends on `pdfjs-dist`, keep major versions compatible so the worker matches the library.
|
|
12
14
|
|
|
13
15
|
## Usage
|
|
14
16
|
|
|
15
17
|
```js
|
|
16
|
-
import { Zine } from '@zinejs/core'
|
|
17
|
-
import { PdfSource } from '@zinejs/pdf'
|
|
18
|
+
import { Zine } from '@zinejs/core'
|
|
19
|
+
import { PdfSource } from '@zinejs/pdf'
|
|
18
20
|
|
|
19
|
-
|
|
21
|
+
new Zine(document.getElementById('book'), {
|
|
20
22
|
source: new PdfSource('document.pdf'),
|
|
21
|
-
})
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
Under a bundler that's all you need — the pdf.js worker is resolved for you.
|
|
25
|
-
|
|
26
|
-
### CDN / no bundler
|
|
27
|
-
|
|
28
|
-
Both packages ship **UMD** builds (`dist/index.umd.js`) that share the `ZineJS` global — load **core first**, then pdf (the pdf build uses `extend: true` so it merges into `ZineJS` instead of replacing it).
|
|
29
|
-
|
|
30
|
-
Modern `pdfjs-dist` is ESM-only, so load it in a module script first, expose
|
|
31
|
-
`globalThis.pdfjsLib`, then use classic deferred `<script>` tags for the UMD
|
|
32
|
-
builds (and pass an explicit `workerSrc` — no bundler rewrites the worker URL):
|
|
33
|
-
|
|
34
|
-
```html
|
|
35
|
-
<script type="module">
|
|
36
|
-
import * as pdfjsLib from 'https://cdn.jsdelivr.net/npm/pdfjs-dist/build/pdf.min.mjs';
|
|
37
|
-
globalThis.pdfjsLib = pdfjsLib;
|
|
38
|
-
</script>
|
|
39
|
-
|
|
40
|
-
<script defer src="https://cdn.jsdelivr.net/npm/@zinejs/core/dist/index.umd.js"></script>
|
|
41
|
-
<script defer src="https://cdn.jsdelivr.net/npm/@zinejs/pdf/dist/index.umd.js"></script>
|
|
42
|
-
<script defer>
|
|
43
|
-
const book = new ZineJS.Zine(document.getElementById('book'), {
|
|
44
|
-
source: new ZineJS.PdfSource('document.pdf', {
|
|
45
|
-
workerSrc: 'https://cdn.jsdelivr.net/npm/pdfjs-dist/build/pdf.worker.min.mjs',
|
|
46
|
-
}),
|
|
47
|
-
});
|
|
48
|
-
</script>
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
Image-only books can skip pdf.js and use a plain classic script:
|
|
52
|
-
|
|
53
|
-
```html
|
|
54
|
-
<script src="https://cdn.jsdelivr.net/npm/@zinejs/core/dist/index.umd.js"></script>
|
|
55
|
-
<script>
|
|
56
|
-
new ZineJS.Zine(document.getElementById('book'), {
|
|
57
|
-
source: new ZineJS.ImageSource(['page-01.png', 'page-02.png']),
|
|
58
|
-
});
|
|
59
|
-
</script>
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
`PdfSource` prefers `globalThis.pdfjsLib` when present (CDN), otherwise dynamic-imports `pdfjs-dist` (bundlers).
|
|
63
|
-
|
|
64
|
-
## The pdf.js worker (`workerSrc`)
|
|
65
|
-
|
|
66
|
-
pdf.js parses and rasterizes in a Web Worker, a separate file the host must locate. By default `PdfSource` resolves it to (the `legacy/` path since `legacy` defaults to true; `build/` when `legacy: false`):
|
|
67
|
-
|
|
68
|
-
```js
|
|
69
|
-
new URL('pdfjs-dist/legacy/build/pdf.worker.min.mjs', import.meta.url).href
|
|
23
|
+
})
|
|
70
24
|
```
|
|
71
25
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
### Vite / webpack 5 / esbuild
|
|
26
|
+
Under a bundler that is all you need: the pdf.js worker is resolved for you.
|
|
75
27
|
|
|
76
|
-
|
|
28
|
+
`src` can also be raw bytes or a pdf.js document you already opened:
|
|
77
29
|
|
|
78
30
|
```js
|
|
79
|
-
new PdfSource(
|
|
31
|
+
new PdfSource(arrayBuffer)
|
|
32
|
+
new PdfSource(await getDocument(url).promise)
|
|
80
33
|
```
|
|
81
34
|
|
|
82
|
-
|
|
35
|
+
## The pdf.js worker
|
|
83
36
|
|
|
84
|
-
|
|
37
|
+
pdf.js parses and rasterizes in a Web Worker. By default `PdfSource` points at the **legacy** worker (because `legacy` defaults to `true`):
|
|
85
38
|
|
|
86
39
|
```js
|
|
87
|
-
new
|
|
40
|
+
new URL('pdfjs-dist/legacy/build/pdf.worker.min.mjs', import.meta.url).href
|
|
88
41
|
```
|
|
89
42
|
|
|
90
|
-
|
|
43
|
+
Vite, webpack 5, and esbuild rewrite that literal and emit the asset. Resolution order: `workerSrc` option, then `pdfjsLib.GlobalWorkerOptions.workerSrc`, then the auto-default. Pass `workerSrc` only for CDN / UMD or a file you copied yourself, and keep it on the same build as the library (legacy vs modern).
|
|
91
44
|
|
|
92
|
-
If
|
|
45
|
+
If you already set `GlobalWorkerOptions.workerSrc`, leave `workerSrc` off. A pre-created pdf.js document needs no worker from this package.
|
|
93
46
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
```js
|
|
97
|
-
new PdfSource(arrayBuffer); // raw PDF bytes (ArrayBuffer | Uint8Array)
|
|
98
|
-
new PdfSource(await getDocument(...).promise); // a pdf.js document you created; no workerSrc needed
|
|
99
|
-
```
|
|
47
|
+
CDN / no bundler: load pdf.js first, expose `globalThis.pdfjsLib`, then the UMD builds (core first). See the [HTML CDN example](https://zinejs.com/examples/html-cdn).
|
|
100
48
|
|
|
101
49
|
## Options
|
|
102
50
|
|
|
103
|
-
```
|
|
51
|
+
```js
|
|
104
52
|
new PdfSource(src, {
|
|
105
|
-
workerSrc,
|
|
53
|
+
workerSrc, // override the auto-resolved worker URL
|
|
106
54
|
renderScale: 1, // pages rasterize at renderScale × devicePixelRatio
|
|
107
|
-
preload: 1, // adjacent pages to prefetch
|
|
108
|
-
maxCacheBytes, // soft cap on cached page bytes (default ~256 MB)
|
|
109
|
-
progressive:
|
|
110
|
-
disableAutoFetch:
|
|
111
|
-
legacy: true, //
|
|
112
|
-
})
|
|
55
|
+
preload: 1, // adjacent pages to prefetch (default 1)
|
|
56
|
+
maxCacheBytes, // soft cap on cached page bytes (default ~256 MB)
|
|
57
|
+
progressive: false, // true: low-res first, then crisp
|
|
58
|
+
disableAutoFetch: false, // true: fetch only the ranges visible pages need
|
|
59
|
+
legacy: true, // false: lean modern pdf.js (recent engines only)
|
|
60
|
+
})
|
|
113
61
|
```
|
|
114
62
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
### Legacy vs modern build (`legacy`)
|
|
63
|
+
### Legacy vs modern (`legacy`)
|
|
118
64
|
|
|
119
|
-
pdf.js ships two builds. The
|
|
65
|
+
pdf.js ships two builds. The **legacy** build is transpiled with polyfills and is the default, so PDF books stay usable on older engines as well as current ones. The **modern** build is smaller and a touch faster. Pass `legacy: false` when your audience is on recent browsers:
|
|
120
66
|
|
|
121
67
|
```js
|
|
122
|
-
new PdfSource('document.pdf', { legacy: false })
|
|
68
|
+
new PdfSource('document.pdf', { legacy: false })
|
|
123
69
|
```
|
|
124
70
|
|
|
125
|
-
The flag also picks the matching worker
|
|
71
|
+
The flag also picks the matching worker. It is ignored when you pass a pre-created document or set `globalThis.pdfjsLib`, since those already chose their build.
|
|
72
|
+
|
|
73
|
+
Mozilla documents legacy as Chrome 125+, Firefox ESR, Safari 18+, and Chromium Edge. We have seen PDF text rasterize correctly back to Chrome 114. Full notes: [browser support](https://github.com/awecode/zinejs#browser-support).
|