- extractImages returns inline images and image masks as RGBA pixels or as PNG with format 'png', each with its position on the page in bounds behavior changed · inferred, marked in the notes below
- inspectPages measures text and image coverage per page, e.g. to distinguish scanned pages from born-digital ones
- renderPageAsImage accepts format 'png', 'jpeg', or 'webp' and a quality option
- With pdfjs-dist installed, CMaps and standard fonts load from that package in Node.js so CJK text without embedded mappings extracts correctly
- getMeta types the /Info dictionary as PDFInfo
- unpdf now ships as ESM only and requires Node.js 24; CommonJS builds are removed requirement raised · inferred, marked in the notes belowremoved · inferred, marked in the notes below
- definePDFJSModule stores the loader and loads PDF.js on first use; configureUnPDF and resolvePDFJSImport are removed
- extractLinks returns links as one array per page signature changed · inferred, marked in the notes below
- renderPageAsImage returns a Uint8Array signature changed · inferred, marked in the notes below
- A scale, width, or height of 0 passed to renderPageAsImage now throws instead of falling back to a scale of 1 behavior changed · inferred, marked in the notes below
- ExtractedImageObject is renamed to ExtractedImage; data always holds four bytes per pixel, the channels property is removed, and key is null for small inline images renamed · inferred, marked in the notes below
- getMeta info is typed as PDFInfo and metadata as Metadata | null, with non-standard /Info entries placed in info.Custom as a Map signature changed · inferred, marked in the notes below
- In Node.js with pdfjs-dist installed, getDocumentProxy sets useSystemFonts to false by default so non-embedded standard fonts use PDF.js' own font files behavior changed · inferred, marked in the notes below
- Pages are inspected one at a time and their resources are released
- CMaps and standard fonts load from the local pdfjs-dist in Node.js
- Images of annotation appearances are placed on the page
- renderPageAsImage sizes, formats, and canvas detection are hardened
- Soft masks and hidden layers are ignored when extracting images and inspecting pages
- Standard fonts of pdfjs-dist are used in Node.js
- renderPageAsImage accepts RenderPageAsImageOptions and Metadata is exported
- configureUnPDF is removed inferred, marked in the notes below
- resolvePDFJSImport is removed inferred, marked in the notes below
- createIsomorphicCanvasFactory is removed; each document exposes PDF.js' canvas factory as pdf.canvasFactory inferred, marked in the notes below
- The channels property of extracted images is removed inferred, marked in the notes below
9 changes to check, marked in the notes below
From unpdf
unpdf 2.0 is here! 🎉
This major release extracts every image on a page, adds page inspection and more rendering formats, and trims the API. unpdf now ships as ESM only and requires Node.js 24.
🔥 What's New
- Complete image extraction –
extractImagesreturns inline images and image masks too, as RGBA pixels or as PNG withformat: 'png', each with its position on the page inbounds. - Page inspection –
inspectPagesmeasures text and image coverage per page, e.g. to tell scanned pages from born-digital ones. - JPEG and WebP rendering –
renderPageAsImagetakesformat: 'png' | 'jpeg' | 'webp'and aquality. - CMaps and standard fonts in Node.js – with
pdfjs-distinstalled, both load from that package, so CJK text without embedded mappings extracts correctly. - Typed metadata –
getMetatypes the/Infodictionary asPDFInfo.
🚀 How to Upgrade
pnpm add unpdf@^2
unpdf 2 requires Node.js 24 or later. CommonJS builds are gone – replace require('unpdf') with import. The steps below cover every other breaking change. requirement raised · inferred removed · inferred
1. Define PDF.js Without await
definePDFJSModule stores the loader and loads PDF.js on first use. configureUnPDF and resolvePDFJSImport are removed. removed · inferred
- await configureUnPDF({ pdfjs: () => import('pdfjs-dist/legacy/build/pdf.mjs') })
+ definePDFJSModule(() => import('pdfjs-dist/legacy/build/pdf.mjs'))
A loader that fails now throws on the first call of another method. To load PDF.js up front, call await getResolvedPDFJS() where you used resolvePDFJSImport().
2. Flatten extractLinks for All Links
links holds one array per page. signature changed · inferred
const { links } = await extractLinks(pdf)
+ const allLinks = links.flat()
3. Use the Uint8Array From renderPageAsImage signature changed · inferred
const image = await renderPageAsImage(pdf, 1, {
canvasImport: () => import('@napi-rs/canvas'),
})
- await writeFile('page.png', new Uint8Array(image))
+ await writeFile('page.png', image)
A scale, width, or height of 0 now throws instead of falling back to a scale of 1. createIsomorphicCanvasFactory is removed – each document carries PDF.js' own canvas factory as pdf.canvasFactory. behavior changed · inferred removed · inferred
4. Read Extracted Images as RGBA
ExtractedImageObject is now ExtractedImage. data always holds four bytes per pixel, so channels is gone, and key is null for small inline images. renamed · inferred removed · inferred
const [image] = await extractImages(pdf, 1)
await sharp(image.data, {
- raw: { width: image.width, height: image.height, channels: image.channels },
+ raw: { width: image.width, height: image.height, channels: 4 },
}).toFile('image.png')
Or drop sharp and pass { format: 'png' }. A page may now return more images than before, since inline images and image masks count, or fewer, since images inside soft masks and hidden layers are skipped. behavior changed · inferred
5. Check the getMeta Types
info is typed as PDFInfo and metadata as Metadata | null – the runtime values are unchanged. Non-standard /Info entries sit in info.Custom, a Map. signature changed · inferred
- const title = metadata.get('dc:title')
+ const title = metadata?.get('dc:title')
6. Expect Standard Fonts in Node.js Renders
With pdfjs-dist installed, getDocumentProxy sets useSystemFonts: false in Node.js and draws non-embedded standard fonts with PDF.js' own font files instead of the host's. To keep the host fonts, pass useSystemFonts: true to getDocumentProxy. behavior changed · inferred
🚨 Breaking Changes
- Ship ESM only and require Node.js 24 - by @johannschopplich (d0d6c)
- Load the defined PDF.js module on first use and drop
configureUnPDF- by @johannschopplich (e1ed1) - Return
extractLinksresults per page - by @johannschopplich (31ec4) - Type
getMetainfo fields and returnnullwithout XMP metadata - by @johannschopplich (9bb12) - Return rendered pages as
Uint8Arrayand add JPEG and WebP output - by @johannschopplich (62fc4) - Extract all images of a page as RGBA or PNG with their placement - by @johannschopplich (4b7b9)
🚀 Features
- Add
inspectPagesfor per-page text and image measurements - by @johannschopplich (7459a)
🐞 Bug Fixes
- Load CMaps and standard fonts from the local
pdfjs-distin Node.js - by @johannschopplich (7051f) - Place images of annotation appearances on the page - by @johannschopplich (8b7e7)
- Harden
renderPageAsImagesizes, formats, and canvas detection - by @johannschopplich (623e9) - Ignore soft masks and hidden layers when extracting images and inspecting pages - by @johannschopplich (5bcb2)
- Use the standard fonts of
pdfjs-distin Node.js - by @johannschopplich (3da7a) - Accept
RenderPageAsImageOptionsinrenderPageAsImageand exportMetadata- by @johannschopplich (bcf52)
🏎 Performance
- Inspect pages one at a time and release their resources - by @johannschopplich (8239f)