unpdf v2.0.0

v2.0.0
Added 5
  • 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
Changed 9
Fixed 6
  • 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
Removed 4

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 – extractImages returns inline images and image masks too, as RGBA pixels or as PNG with format: 'png', each with its position on the page in bounds.
  • Page inspection – inspectPages measures text and image coverage per page, e.g. to tell scanned pages from born-digital ones.
  • JPEG and WebP rendering – renderPageAsImage takes format: 'png' | 'jpeg' | 'webp' and a quality.
  • CMaps and standard fonts in Node.js – with pdfjs-dist installed, both load from that package, so CJK text without embedded mappings extracts correctly.
  • Typed metadata – getMeta types the /Info dictionary as PDFInfo.
🚀 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 extractLinks results per page  -  by @johannschopplich (31ec4)
  • Type getMeta info fields and return null without XMP metadata  -  by @johannschopplich (9bb12)
  • Return rendered pages as Uint8Array and 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 inspectPages for per-page text and image measurements  -  by @johannschopplich (7459a)
   🐞 Bug Fixes
  • Load CMaps and standard fonts from the local pdfjs-dist in Node.js  -  by @johannschopplich (7051f)
  • Place images of annotation appearances on the page  -  by @johannschopplich (8b7e7)
  • Harden renderPageAsImage sizes, 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-dist in Node.js  -  by @johannschopplich (3da7a)
  • Accept RenderPageAsImageOptions in renderPageAsImage and export Metadata  -  by @johannschopplich (bcf52)
   🏎 Performance
  • Inspect pages one at a time and release their resources  -  by @johannschopplich (8239f)
    View changes on GitHub
View original

Upgraded? How did it go?

Discussion