@react-pdf-kit/viewer relies on modern browser APIs. If your users are on older browsers, there are two methods you can choose from:

1. Polyfills: Load the dedicated @react-pdf-kit/polyfills package to support older browsers
2. Polyfills and Legacy PDF.js Worker: Load the @react-pdf-kit/polyfills and override with a Legacy PDF.js Worker to support even more older browsers than the first method.

Polyfills Library

@react-pdf-kit/polyfills package is used to fill in gaps of certain functions in older browsers before any viewer code runs. The bundle is kept in a separate package so it can be versioned independently from the viewer.

The polyfills library will support the following browsers:

Chrome	Firefox	Edge	Safari	Safari iOS	Chrome Android
119+	93+	119+	18.3+	18.3+	119+

React (Vite / Webpack / CRA)

For standard React apps, importing the package at the top of your entry point is all that is needed. The side-effect import runs the polyfills synchronously before the rest of the module graph executes.

1. Install @react-pdf-kit/polyfills:

   pnpm

   pnpm add @react-pdf-kit/polyfills

   npm

   npm install @react-pdf-kit/polyfills --save

   yarn

   yarn add @react-pdf-kit/polyfills

   bun

   bun add @react-pdf-kit/polyfills

2. Import the package at the very top of your entry file, before any other imports:

   JSX

   src/main.jsx

   import '@react-pdf-kit/polyfills'
   
   import React from 'react'
   import ReactDOM from 'react-dom/client'
   import App from './App'
   
   ReactDOM.createRoot(document.getElementById('root')).render(
     <React.StrictMode>
       <App />
     </React.StrictMode>
   )

   TSX

   src/main.tsx

   import '@react-pdf-kit/polyfills'
   
   import React from 'react'
   import ReactDOM from 'react-dom/client'
   import App from './App'
   
   ReactDOM.createRoot(document.getElementById('root')!).render(
     <React.StrictMode>
       <App />
     </React.StrictMode>
   )

   Tip

   Placing the import first guarantees the polyfills run before any code that depends on the patched APIs.

Next.js

Next.js automatically replaces polyfill imports with its own built-in polyfills at compile time, so a bare import '@react-pdf-kit/polyfills' will never execute. To work around this, the polyfills bundle is copied to public/ at build time and loaded via a <Script> component with strategy="beforeInteractive", which bypasses Next.js’s polyfill substitution and ensures the bundle runs before hydration.

1. Install @react-pdf-kit/polyfills.

   pnpm

   pnpm add @react-pdf-kit/polyfills

   npm

   npm install @react-pdf-kit/polyfills --save

   yarn

   yarn add @react-pdf-kit/polyfills

   bun

   bun add @react-pdf-kit/polyfills

2. Copy the bundle at build time in next.config.mjs:

   next.config.mjs

   import { copyFileSync } from 'fs'
   import { resolve } from 'path'
   
   copyFileSync(
     resolve(__dirname, 'node_modules/@react-pdf-kit/polyfills/dist/index.cjs.js'),
     resolve(__dirname, 'public/polyfills.js'),
   )
   
   /** @type {import('next').NextConfig} */
   const nextConfig = {
     // ...your config
   }
   
   export default nextConfig

   This runs once during the build and places the bundle at public/polyfills.js so Next.js serves it as a static file.

3. Create a Polyfills component that loads the script before any other JavaScript:

   JSX

   app/_components/PdfViewer/Polyfills.jsx

   import Script from 'next/script'
   
   export default function Polyfills() {
     return <Script src="/polyfills.js" strategy="beforeInteractive" />
   }

   TSX

   app/_components/PdfViewer/Polyfills.tsx

   import Script from 'next/script'
   
   export default function Polyfills() {
     return <Script src="/polyfills.js" strategy="beforeInteractive" />
   }

   Tip

   Using strategy="beforeInteractive" ensures the polyfills are executed before hydration begins — the safest option for filling browser gaps.

4. Render <Polyfills /> in your root layout so it applies to every page:

   JSX

   app/layout.jsx

   import Polyfills from './_components/PdfViewer/Polyfills'
   
   export default function RootLayout({ children }) {
     return (
       <html lang="en">
         <body>
           <Polyfills />
           {children}
         </body>
       </html>
     )
   }

   TSX

   app/layout.tsx

   import Polyfills from './_components/PdfViewer/Polyfills'
   
   export default function RootLayout({ children }: { children: React.ReactNode }) {
     return (
       <html lang="en">
         <body>
           <Polyfills />
           {children}
         </body>
       </html>
     )
   }

Override the PDF.js Worker

The standard PDF.js worker tend to support on modern browsers only. You can install @react-pdf-kit/polyfills together with the legacy PDF.js worker build to extend browser compatibility.

This method will support the following browser as shown below:

Chrome	Firefox	Edge	Safari	Safari iOS	Chrome Android
101+	101+	101+	16.5+	16.5+	101+

Note

Skip this section if all your target browsers are in the ✅ Polyfills Library above.

1. It’s important to complete the first method of installing the Polyfills library.

2. Install pdfjs-dist:

   pnpm

   pnpm add pdfjs-dist

   npm

   npm install pdfjs-dist --save

   yarn

   yarn add pdfjs-dist

   bun

   bun add pdfjs-dist

   Tip

   The legacy worker path (legacy/build/pdf.worker.min.mjs) is available in corresponding PDF.js versions. @react-pdf-kit/viewer uses 5.4.530 by default.

3. Pass the legacy worker URL to RPConfig via the workerUrl prop:

   JSX

   app/components/AppProviders.jsx

   import { RPConfig } from '@react-pdf-kit/viewer'
   
   const workerSrc = new URL(
     'pdfjs-dist/legacy/build/pdf.worker.min.mjs',
     import.meta.url,
   ).toString()
   
   export default function AppProviders({ children, ...props }) {
     return (
       <RPConfig workerUrl={workerSrc} {...props}>
         {children}
       </RPConfig>
     )
   }

   TSX

   app/components/AppProviders.tsx

   import { RPConfig, RPConfigProps } from '@react-pdf-kit/viewer'
   import { type PropsWithChildren } from 'react'
   
   const workerSrc = new URL(
     'pdfjs-dist/legacy/build/pdf.worker.min.mjs',
     import.meta.url,
   ).toString()
   
   export default function AppProviders({ children, ...props }: PropsWithChildren<Omit<RPConfigProps, 'workerUrl'>>) {
     return (
       <RPConfig workerUrl={workerSrc} {...props}>
         {children}
       </RPConfig>
     )
   }