@embedpdf/engines

@embedpdf/engines is a high-performance JavaScript library for rendering and manipulating PDF files. Built on the robust PDFium engine compiled to WebAssembly, it provides a simple, modern API that works everywhere—from the browser to the server.

Quick Start

The best way to use the engine in a browser is with a Web Worker to keep the main thread free. Here’s a complete example of rendering the first page of a PDF:

1. Create your worker (webworker.ts):


import { PdfiumEngineRunner } from '@embedpdf/engines';
 
async function init() {
  const response = await fetch(
    'https://cdn.jsdelivr.net/npm/@embedpdf/pdfium/dist/pdfium.wasm'
  );
  const wasmBinary = await response.arrayBuffer();
  const runner = new PdfiumEngineRunner(wasmBinary);
  runner.prepare();
}
 
init();

2. Use the engine in your app (main.ts):


import { WebWorkerEngine } from '@embedpdf/engines/worker';
 
const worker = new Worker(new URL('./webworker.ts', import.meta.url), { 
  type: 'module' 
});
const engine = new WebWorkerEngine(worker);
 
// Initialize the engine
await engine.initialize().toPromise();
 
// Open a document and render its first page
const document = await engine
  .openDocumentUrl({ id: 'demo', url: '/demo.pdf' })
  .toPromise();
 
const imageBlob = await engine
  .renderPage(document, document.pages[0])
  .toPromise();
 
// You can now display the image
const imageUrl = URL.createObjectURL(imageBlob);
document.getElementById('my-image').src = imageUrl;

Core Features

Universal: Run the same code in web browsers (using Web Workers for performance), Node.js, and serverless functions.
High-Level API: Forget the complexities of WASM. The engine provides a clean, asynchronous API for common tasks like rendering pages, extracting text, and managing annotations.
Fully Typed: Written entirely in TypeScript for excellent autocompletion and type safety in your projects.
Worker-Optimized: Built from the ground up to offload heavy PDF processing from the main UI thread, ensuring your app stays fast and responsive.

Framework Integrations

While @embedpdf/engines is framework-agnostic, we provide helpers to make integration seamless with popular frameworks.

React

For React applications, the usePdfiumEngine hook is the recommended way to manage the engine’s lifecycle. It handles initialization and cleanup automatically within your components.

➡️ Learn more in the Using with React guide.

Vue

For Vue 3 applications, we provide a usePdfiumEngine composable that ties the engine’s lifecycle to your component, providing reactive state for loading and errors.

➡️ Learn more in the Using with Vue guide.

Installation


npm i @embedpdf/engines @embedpdf/pdfium


pnpm add @embedpdf/engines @embedpdf/pdfium


yarn add @embedpdf/engines @embedpdf/pdfium


bun add @embedpdf/engines @embedpdf/pdfium

Usage Patterns

While a Web Worker is recommended for browsers, the engine is flexible and supports other environments.

1. Main Thread (Browser)

For simpler use cases, you can run the engine directly on the main thread.


import { init } from '@embedpdf/pdfium';
import { PdfiumEngine } from '@embedpdf/engines/pdfium';
 
const response = await fetch(
  'https://cdn.jsdelivr.net/npm/@embedpdf/pdfium/dist/pdfium.wasm'
);
const wasmBinary = await response.arrayBuffer();
const pdfium = await init({ wasmBinary });
 
const engine = new PdfiumEngine(pdfium);
await engine.initialize().toPromise();
// ... use engine methods

2. Node.js

The engine works seamlessly in Node.js. You’ll need to provide an image conversion library like sharp.


import { readFile, writeFile } from 'fs/promises';
import sharp from 'sharp';
import { init } from '@embedpdf/pdfium';
import { PdfiumEngine } from '@embedpdf/engines/pdfium';
import { createNodeImageDataToBufferConverter } from '@embedpdf/engines/converters';
 
const imageDataConverter = createNodeImageDataToBufferConverter(sharp);
const pdfiumInstance = await init();
const engine = new PdfiumEngine(pdfiumInstance, {
  imageDataConverter
});
await engine.initialize().toPromise();
 
const pdfBuffer = await readFile('document.pdf');
const document = await engine
  .openDocumentBuffer({ id: 'sample', content: pdfBuffer })
  .toPromise();
 
const imageBuffer = await engine
  .renderPage(document, document.pages[0])
  .toPromise();
  
await writeFile('output.webp', imageBuffer);