PDF.js for TYPO3

PDF.js embeds Mozilla’s battle-tested PDF renderer directly into TYPO3 pages, the lightweight answer when editors want to show PDFs in the browser without forcing a download and without a heavy flipbook layer

When visitors click on a PDF, the browser either opens it in a new tab, downloads it or hands it over to an external viewer. None of these variants is satisfactory for editors who want to present a document in the context of a page. PDF.js solves this by embedding the viewer that Firefox and Chrome use internally as a standalone JavaScript module directly in the TYPO3 page. The result is consistent display across all browsers and devices, without users having to install a plug-in or leave the document.

An often overlooked advantage: the user does not leave the page. While an opened PDF in a new tab usually means the end of the session, the analytics connection remains intact with the embedded viewer. Anyone measuring how long visitors actually spend with a document can attribute the time directly to the content page and see which documents are really being read.

Typical use cases

The most common use case is embedding single documents on content pages, for example a whitepaper on a product page, an application form on a service page or an event programme next to the event description. The editorial team uploads the PDF into FAL and references it through a content element, and PDF.js renders it inline. The visual corporate design of the page is preserved because frames, shadows and controls are styled through the project’s sitepackage template.

The second case is download centres where several PDFs are presented with previews. Instead of blind file icons, users see the first page of the document and can decide with one click whether to read on or start the full download. For catalogues, forms and info sheets, this preview is often the decisive factor whether a document gets clicked at all.

Thirdly: low-barrier delivery of government and university documents. PDF.js makes the text layer of the PDF available, so that screen readers can read out the content, provided the PDF was correctly exported as a “tagged PDF”.

Technical architecture

For TYPO3, PDF.js exists in two flavours: as a classic TYPO3 extension that delivers the JavaScript library and adds a content element in the backend, or as a pure sitepackage integration where the PDF.js assets end up directly in the project’s frontend build. The extension variant is more comfortable for editors because they can configure file selection, default zoom and preview parameters through the TYPO3 backend. The sitepackage variant is cleaner for developers because they control the version and integrate it into the existing build process.

Technically, PDF.js consists of two parts: a parser that loads the PDF file and breaks it down into an internal object graph, and a viewer that renders these objects into a canvas element. Both parts run entirely client-side. The worker approach ensures that parsing happens in a separate thread and does not block the main thread, which is important for smooth scrolling through large documents.

Integration runs through a TypoScript block and a Fluid partial that embeds an iframe or a container with the viewer. The URL of the PDF is passed as a query parameter, and the configuration of the UI elements (zoom buttons, page navigation, download link) runs through the viewer configuration block of PDF.js.

Common problems and solutions

The first problem is cross origin. When the PDF is loaded from a different domain or an S3 bucket, the browser blocks access for security reasons. The solution is either a correct CORS configuration on the file server or a server-side proxy via a TYPO3 middleware that serves the PDF under the same domain.

Second problem: performance on large documents. A 200-page manual loads quickly because the viewer only renders the visible pages. It becomes problematic when the PDF itself is not optimised for the web and every single image is embedded at full print resolution. The only fix is to downscale the source document with Ghostscript or a comparable tool before it enters FAL.

Third problem: accessibility without a text layer. If the PDF is a pure scan without OCR, screen readers receive no text. In that case PDF.js alone is of no help: the PDF has to go through an OCR pass first. For public authorities, this is not an option but a legal obligation under accessibility standards.

Migration and version compatibility

PDF.js as a library is continuously maintained by Mozilla and is in principle independent of the TYPO3 version. However, the TYPO3 extension wrappers that integrate PDF.js often lag behind the library version. Anyone upgrading to TYPO3 v12 or v13 should check whether the extension they use has a compatible version or whether switching to a sitepackage integration is the better path.

In direct comparison to pdfviewhelpers (server-side PDF generation) and rflipbook (flipbook effect), PDF.js is the option with the lowest overhead and the highest browser compatibility. For individual PDF embeds it is almost always the better choice than a heavy flipbook solution.

Anyone who embeds PDF.js in their sitepackage themselves should define a clear versioning strategy. The library receives regular security updates because PDF parsers are historically a popular attack target. An annual update rhythm is the minimum; for public authorities and critical infrastructure, quarterly makes more sense. Integration via npm and a frontend build process makes this much easier than a classic copy into the project directory.

Gosign integrates PDF.js as a sitepackage component or as a TYPO3 extension, depending on how much control editors need. For existing projects with legacy viewers, Gosign guides the migration and makes sure that accessibility and load time are not sacrificed for comfort.