DEV Community: StreamPDF

PDF.js Deep Dive 2: getDocument & getPage

StreamPDF — Thu, 22 Oct 2026 13:00:00 +0000

Introduction

This is the second article in the PDF.js Deep Dive series, continuing from the architecture overview in article 1. We'll dive into the Display layer and trace the execution paths of getDocument and getPage. All code snippets in this article are based on PDF.js v6.3.289.

PDF.js Deep Dive 1: The Architecture of PDF.js

The `getDocument` Method

Step 1: Create the loading task and global ID generator

// Source: src/display/api.js
const task = new PDFDocumentLoadingTask();
const { docId } = task;

PDFDocumentLoadingTask also doubles as PDF.js's global ID generator — the docId it produces is used to identify this document throughout the worker.

Step 2: Process user parameters

const url = src.url ? getUrlProp(src.url) : null;
const data = src.data ? getDataProp(src.data) : null;
const httpHeaders = src.httpHeaders || null;
const withCredentials = src.withCredentials === true;
const password = src.password ?? null;
// ...
const transportFactory = {
  canvasFactory: new CanvasFactory({ ownerDocument, enableHWA }),
  filterFactory: new FilterFactory({ docId, ownerDocument }),
  binaryDataFactory:
    (typeof PDFJSDev !== 'undefined' && PDFJSDev.test('MOZCENTRAL')) || useWorkerFetch
      ? null
      : new BinaryDataFactory({ cMapUrl, standardFontDataUrl, wasmUrl }),
};

Step 3: Create the Worker

if (!worker) {
  // Worker was not provided -- creating and owning our own. If message port
  // is specified in global worker options, using it.
  worker = PDFWorker.create({
    verbosity,
    port: GlobalWorkerOptions.workerPort,
  });
  task._worker = worker;
}

Callers can pass in their own Worker instance, but in the common case PDF.js handles Worker creation internally.

PDFWorker is a class; we invoke its static create method.

Entering getDocument → PDFWorker.create

// Source: src/display/api.js
static create(params) {
  const cachedPort = this.#workerPorts.get(params?.port);
  if (cachedPort) {
    if (cachedPort._pendingDestroy) {
      throw new Error(
        "PDFWorker.create - the worker is being destroyed.\n" +
          "Please remember to await `PDFDocumentLoadingTask.destroy()`-calls."
      );
    }
    return cachedPort;
  }
  return new PDFWorker(params);
}

PDFWorker maintains a static #workerPorts Map keyed by port, which caches previously created Worker instances so the same port isn't instantiated twice. If a cached entry exists, it returns it directly; otherwise it constructs a fresh PDFWorker.

Entering getDocument → PDFWorker.create → PDFWorker

// Source: src/display/api.js
constructor({
  name = null,
  port = null,
  verbosity = getVerbosityLevel(),
} = {}) {
  this.name = name;
  this.destroyed = false;
  this.verbosity = verbosity;

  if (port) {
    if (PDFWorker.#workerPorts.has(port)) {
      throw new Error("Cannot use more than one PDFWorker per port.");
    }
    PDFWorker.#workerPorts.set(port, this);
    this.#initializeFromPort(port);
  } else {
    this.#initialize();
  }

  if (typeof PDFJSDev === "undefined" || PDFJSDev.test("TESTING")) {
    // For testing purposes.
    Object.defineProperty(this, "_webWorker", {
      get() {
        return this.#webWorker;
      },
    });
  }
}

Since we don't pass a port, the constructor calls #initialize.

Entering getDocument → PDFWorker.create → PDFWorker → #initialize

if (PDFWorker.#isWorkerDisabled || PDFWorker.#mainThreadWorkerMessageHandler) {
  this.#setupFakeWorker();
  return;
}
let { workerSrc } = PDFWorker;
// ...
if (
  typeof PDFJSDev !== 'undefined' &&
  PDFJSDev.test('GENERIC') &&
  !PDFWorker._isSameOrigin(window.location, workerSrc)
) {
  workerSrc = PDFWorker._createCDNWrapper(new URL(workerSrc, window.location).href);
}
const worker = new Worker(workerSrc, { type: 'module' });
const messageHandler = new MessageHandler('main', 'worker', worker);
// ...

First it checks whether to fall back to a "fake worker" (run PDF parsing on the main thread). In our case we take the normal path, skip the fake-worker branch, and read workerSrc from a static getter.

Entering getDocument → PDFWorker.create → PDFWorker → #initialize → workerSrc

static get workerSrc() {
  if (GlobalWorkerOptions.workerSrc) {
    return GlobalWorkerOptions.workerSrc;
  }
  throw new Error('No "GlobalWorkerOptions.workerSrc" specified.');
}

This is the option we set at startup:

pdfjsLib.GlobalWorkerOptions.workerSrc =
  'https://cdn.jsdelivr.net/npm/pdfjs-dist@6.3.289/build/pdf.worker.min.mjs';

Back to getDocument → PDFWorker.create → PDFWorker → #initialize

Next, PDF.js handles a potential cross-origin issue: if workerSrc and the current page are on different origins, it wraps the URL in a Blob to bypass the Worker origin check. In our demo the worker is same-origin, so we skip this branch.

What is the Worker cross-origin issue?

The browser's native new Worker(url) only accepts same-origin script URLs. If workerSrc points to a CDN (e.g. https://cdn.jsdelivr.net/...) that differs from your page's origin, the browser rejects Worker creation outright with Failed to construct 'Worker'.

PDF.js's fix is _createCDNWrapper: it generates a tiny snippet of JS — await import("${url}"); — wraps it in a Blob, then calls URL.createObjectURL to produce a blob URL. A blob URL inherits the origin of the page that created it, so new Worker(blobUrl) looks same-origin to the browser. The wrapper's import call itself can load ES modules cross-origin, which gives PDF.js an indirect way around the restriction.

In our demo the worker script is same-origin, so _isSameOrigin returns true and this wrapper path is never triggered.

A few lines later the Worker is instantiated as an ES Module:

const worker = new Worker(workerSrc, { type: 'module' });

and the main-to-worker communication channel is created:

const messageHandler = new MessageHandler('main', 'worker', worker);

MessageHandler is an abstraction that wraps the underlying postMessage-based communication between the main thread and the Worker.

Worker ↔ main handshake

PDF.js then performs a short handshake between the two threads:

const terminateEarly = () => {
  ac.abort();
  messageHandler.destroy();
  worker.terminate();
  if (this.destroyed) {
    this.#capability.reject(new Error('Worker was destroyed'));
  } else {
    // Fall back to fake worker if the termination is caused by an
    // error (e.g. NetworkError / SecurityError).
    this.#setupFakeWorker();
  }
};

const ac = new AbortController();
worker.addEventListener(
  'error',
  () => {
    if (!this.#webWorker) {
      // Worker failed to initialize due to an error. Clean up and fall
      // back to the fake worker.
      terminateEarly();
    }
  },
  { signal: ac.signal },
);

messageHandler.on('test', data => {
  ac.abort();
  if (this.destroyed || !data) {
    terminateEarly();
    return;
  }
  this.#messageHandler = messageHandler;
  this.#port = worker;
  this.#webWorker = worker;

  this.#resolve();
});

messageHandler.on('ready', data => {
  ac.abort();
  if (this.destroyed) {
    terminateEarly();
    return;
  }
  try {
    sendTest();
  } catch {
    // We need fallback to a faked worker.
    this.#setupFakeWorker();
  }
});

const sendTest = () => {
  const testObj = new Uint8Array();
  // Ensure that we can use `postMessage` transfers.
  messageHandler.send('test', testObj, [testObj.buffer]);
};

// It might take time for the worker to initialize. We will try to send
// the "test" message immediately, and once the "ready" message arrives.
// The worker shall process only the first received "test" message.
sendTest();

It listens for error, ready, and test, then calls sendTest immediately to probe the channel.

Let's look at what happens on the Worker side when new Worker(...) is called.

Entering main → new Worker

// Source: src/core/worker.js
static {
  // Worker thread (and not Node.js)?
  if (
    typeof window === "undefined" &&
    !isNodeJS &&
    typeof self !== "undefined" &&
    /* isMessagePort = */
    typeof self.postMessage === "function" &&
    "onmessage" in self
  ) {
    this.initializeFromPort(self);
  }
}

The Worker's entry point is a static block inside WorkerMessageHandler. It detects that it's running in a Worker environment and calls initializeFromPort.

Entering main → new Worker → initializeFromPort

static initializeFromPort(port) {
  const handler = new MessageHandler("worker", "main", port);
  this.setup(handler, port);
  handler.send("ready", null);
}

It creates a MessageHandler for the worker→main direction, calls setup, and then signals ready back to main.

Entering main → new Worker → initializeFromPort → setup

// Source: src/core/worker.js (WorkerMessageHandler.setup)
static setup(handler, port) {
  let testMessageProcessed = false;
  handler.on("test", data => {
    if (testMessageProcessed) {
      return; // we already processed 'test' message once
    }
    testMessageProcessed = true;

    // Ensure that `TypedArray`s can be sent to the worker.
    handler.send("test", data instanceof Uint8Array);
  });

  handler.on("configure", data => {
    setVerbosityLevel(data.verbosity);
  });

  handler.on("GetDocRequest", data => this.createDocumentHandler(data, port));

  if (typeof PDFJSDev === "undefined" || PDFJSDev.test("TESTING")) {
    handler.on("GetWorkerCoverage", function () {
      return globalThis.__coverage__ ?? {};
    });
  }
}

The worker registers handlers for three messages: test, configure, and GetDocRequest. The test handler is one-shot — it sets testMessageProcessed to true and echoes back.

Now back to the main thread: when the Worker's ready arrives, main resends test. But the Worker's testMessageProcessed flag is already true, so the retry is silently discarded. Only the very first test message gets a response. Once main receives that acknowledgement, it calls #resolve(), marking worker.promise as complete.

Here's the full handshake visualized:

The two vertical lanes represent main (left) and worker (right), with time flowing downward.

① Right after new Worker, main sends a test probe that validates postMessage transfer semantics;

② After finishing initializeFromPort, the worker replies with ready, telling main it is now ready;

③ Main resends test after receiving ready, but the worker only processes the first one — testMessageProcessed is a one-shot switch. This retry (dashed in the diagram) is dropped at if (testMessageProcessed) { return; };

④ The worker responds only to the first test. Main then removes its error listener and calls #resolve(), completing worker.promise.

Q: Which test message is actually consumed, and why is the retry sent?
A: The first one is always consumed — the ① probe fired right after new Worker. On the worker side, testMessageProcessed is a one-shot switch: when the first message arrives, the flag is false, so it flips to true and echoes back a test ack. Every subsequent test (the ③ retry in the diagram) hits if (testMessageProcessed) { return; } and is silently dropped.

Why can we be sure it's the first? Main and worker share a single ordered MessagePort. The first sendTest() (right after Worker creation) is guaranteed to be enqueued before the retry triggered by ready. The worker only starts dispatching the message queue after its initial script runs and setup() registers the test handler, so that first message is never "missed" — it always hits the one-shot switch.

Then why retry at all? The source code comment spells it out: "It might take time for the worker to initialize." The worker starts slower than the caller, and main doesn't know whether it's ready. PDF.js uses a "probe optimistically first + retry after ready" strategy. In the rare case where the first test isn't dispatched before the switch flips, the retry acts as a fallback. The testMessageProcessed flag ensures the retry can't produce a duplicate ack — keeping the whole process idempotent.

On top of that, try { sendTest(); } catch { this.#setupFakeWorker(); } in the ready callback also acts as a channel health check: if the message can't even be sent, the Worker channel is dead and PDF.js falls back to the fake worker. So the retry is fundamentally about handshake robustness, not about "the second try being the one that works."

Milestone ✅ Worker handshake complete: main creates the Worker thread, confirms the channel works through the test / ready / test exchange, and the Worker instance is ready.

main → Worker: `GetDocRequest`

Once the handshake is done, main waits for both the Worker and GPU to be ready — the GPU check (gpuPromise) determines whether certain rendering paths can use hardware acceleration later.

Promise.all([worker.promise, gpuPromise])
  .then(function ([, hasGPU]) {
    if (worker.destroyed) {
      throw new Error("Worker was destroyed");
    }

    docParams.evaluatorOptions.hasGPU = hasGPU;

    const workerIdPromise = worker.messageHandler.sendWithPromise(
      "GetDocRequest",
      docParams,
      data ? [data.buffer] : null
    );

Main sends a GetDocRequest message through the Worker-level messageHandler.

The Worker's handler is registered in setup:

Worker: on GetDocRequest

handler.on('GetDocRequest', data => this.createDocumentHandler(data, port));

This triggers createDocumentHandler:

Worker: on GetDocRequest → createDocumentHandler

const workerHandlerName = docId + '_worker';
let handler = new MessageHandler(workerHandlerName, docId, port);

After validating the parameters, it creates a document-specific MessageHandler between main and this document on the worker, registers a long list of message handlers (GetPage, GetDestinations, GetMetadata, GetOutline, Terminate, etc.), and returns workerHandlerName back to main.

Back in getDocument:

} else if (url) {
  if (typeof PDFJSDev !== "undefined" && PDFJSDev.test("MOZCENTRAL")) {
    throw new Error("Not implemented: NetworkStream");
  }
  const NetworkStream = getNetworkStream(url);

  networkStream = new NetworkStream({
    url,
    httpHeaders,
    withCredentials,
    rangeChunkSize,
    disableRange,
    disableStream,
  });
} else {

Since we provided a url, PDF.js instantiates a NetworkStream. It then waits for workerIdPromise to resolve:

return workerIdPromise.then(workerId => {
  if (worker.destroyed) {
    throw new Error('Worker was destroyed');
  }

  const messageHandler = new MessageHandler(docId, workerId, worker.port);
  const transport = new WorkerTransport(
    messageHandler,
    task,
    networkStream,
    transportParams,
    transportFactory,
    pagesMapper,
  );
  task._transport = transport;

  if (task.destroyed) {
    // `destroy()` was called during the worker handshake; the orderly
    // shutdown (including the "Terminate" message) will be issued
    // through the transport once destroy resumes.
    throw new Error('Loading aborted');
  }
  messageHandler.send('Ready', null);
});

Main creates the document-level MessageHandler and a WorkerTransport — the central object that manages this document's lifecycle. Finally it sends the Ready message to kick off actual loading.

Milestone ✅ GetDocRequest complete: Worker registers an independent message-processing chain for this document and returns workerHandlerName; main creates WorkerTransport and sends Ready to begin loading.

main → Worker: `Ready`

Entering Worker: on Ready → setupDoc

// Source: src/core/worker.js
handler.on('Ready', function () {
  setupDoc(docParams);
  docParams = null; // we don't need docParams anymore -- saving memory.
});

setupDoc is the core setup function. It defines three helpers — onSuccess, onFailure, and pdfManagerReady — then calls getPdfManager:

Entering Worker: on Ready → setupDoc → getPdfManager

const pdfManagerArgs = {
  source: null,
  disableAutoFetch,
  docBaseUrl,
  docId,
  enableXfa,
  evaluatorOptions,
  handler,
  length: 0,
  password,
  rangeChunkSize,
};

if (data) {
  pdfManagerArgs.source = data;

  return new LocalPdfManager(pdfManagerArgs);
}
const pdfStream = new PDFWorkerStream({ msgHandler: handler }),
  fullReader = pdfStream.getFullReader();

When raw data bytes are provided, PDF.js uses LocalPdfManager. For URL-based loading it creates a PDFWorkerStream to read data incrementally.

Entering Worker: on Ready → setupDoc → getPdfManager → PDFWorkerStream

class PDFWorkerStream extends BasePDFStream {
  constructor(source) {
    super(source, PDFWorkerStreamReader, PDFWorkerStreamRangeReader);
  }
}

PDFWorkerStream subclasses BasePDFStream and wires in two reader implementations.

Back to Worker: on Ready → setupDoc → getPdfManager

fullReader = pdfStream.getFullReader();

getFullReader is inherited from BasePDFStream:

getFullReader() {
  assert(
    !this._fullReader,
    "BasePDFStream.getFullReader can only be called once."
  );
  return (this._fullReader = new this.#PDFStreamReader(this));
}

It instantiates PDFWorkerStreamReader, which — crucially — sends a GetReader message back to main over the msgHandler:

class PDFWorkerStreamReader extends BasePDFStreamReader {
  _reader = null;

  constructor(stream) {
    super(stream);
    const { msgHandler } = stream._source;

    const readableStream = msgHandler.sendWithStream('GetReader');
    this._reader = readableStream.getReader();

    msgHandler.sendWithPromise('ReaderHeadersReady').then(data => {
      this._contentLength = data.contentLength;
      this._isStreamingSupported = data.isStreamingSupported;
      this._isRangeSupported = data.isRangeSupported;

      this._headersCapability.resolve();
    }, this._headersCapability.reject);
  }
  // ...
}

On the main side, WorkerTransport handles the GetReader message by calling networkStream.getFullReader(), which eventually issues the first actual HTTP request — the fetch call for the PDF itself:

constructor(stream) {
  super(stream);
  const {
    disableRange,
    disableStream,
    rangeChunkSize,
    url,
    withCredentials,
  } = stream._source;

  this._isStreamingSupported = !disableStream;
  const headers = new Headers(stream.headers);

  fetchUrl(url, headers, withCredentials, this._abortController)
    .then(response => {
      stream._responseOrigin = getResponseOrigin(response.url);
      ensureResponseStatus(response.status, url);
      this._reader = response.body.getReader();

      const responseHeaders = response.headers;
      const { contentLength, isRangeSupported } =
        validateRangeRequestCapabilities({
          responseHeaders,
          isHttp: true,
          rangeChunkSize,
          disableRange,
        });
      this._contentLength = contentLength;
      this._isRangeSupported = isRangeSupported;
      this._filename = extractFilenameFromHeader(responseHeaders);

      // We need to stop reading when range is supported and streaming is
      // disabled.
      if (!this._isStreamingSupported && this._isRangeSupported) {
        this.cancel(new AbortException("Streaming is disabled."));
      }

      this._headersCapability.resolve();
    })
    .catch(this._headersCapability.reject);
}

This is where the first network request happens. PDF.js fetches the URL and inspects response headers — content-length, Accept-Ranges, Content-Disposition, etc.

One important detail:

// We need to stop reading when range is supported and streaming is
// disabled.
if (!this._isStreamingSupported && this._isRangeSupported) {
  this.cancel(new AbortException('Streaming is disabled.'));
}

If range requests are available but streaming is off, PDF.js deliberately aborts this initial fetch. You may see the request fire and then immediately cancel — that's not a bug, it's intentional: the probe request only exists to determine whether range is supported. Once that decision is made, PDF.js either switches to NetworkPdfManager (range-capable, reads on-demand) or LocalPdfManager (downloads everything).

This is one of the optimizations built into StreamPDF: our backend guarantees that OSS always supports range requests, eliminating the need for this probe request and moving straight to the next phase.

Back in getPdfManager, once headers are known:

fullReader.headersReady.then(() => {
  if (!fullReader.isRangeSupported) {
    return;
  }
  pdfManagerArgs.source = pdfStream;
  pdfManagerArgs.length = fullReader.contentLength;
  pdfManagerArgs.disableAutoFetch ||= fullReader.isStreamingSupported;

  newPdfManager = new NetworkPdfManager(pdfManagerArgs);
  // ...
  resolve(newPdfManager);
});

If range is supported → NetworkPdfManager (reads data incrementally over the network). If not → the probe request finishes normally, all bytes are buffered, and LocalPdfManager is used instead.

async function readData() {
  let loaded = 0;
  while (true) {
    const { value, done } = await fullReader.read();
    ensureNotTerminated();
    if (done) break;
    // ...
    if (!fullReader.isStreamingSupported) {
      handler.send('DocProgress', { loaded, total: fullReader.contentLength });
    }
    if (newPdfManager) {
      newPdfManager.sendProgressiveData(value);
    } else {
      cachedChunks.push(value);
    }
  }
  if (!newPdfManager) {
    pdfManagerArgs.source = arrayBuffersToBytes(cachedChunks);
    newPdfManager = new LocalPdfManager(pdfManagerArgs);
    resolve(newPdfManager);
  }
}
readData();

Q: Why "LocalPdfManager"? Because once all bytes are in memory, the code path is identical to handling a locally-provided PDF — "local" means the data is fully available, not that it came from disk.

Once getPdfManager resolves, setupDoc continues:

getPdfManager(data)
  .then(function (newPdfManager) {
    // ...
    pdfManager = newPdfManager;

    pdfManager.requestLoadedStream(/* noFetch = */ true).then(
      stream => {
        handler.send('DataLoaded', { length: stream.bytes.byteLength });
      },
      () => {
        /* avoid errors if terminated */
      },
    );
  })
  .then(pdfManagerReady, onFailure);

Then pdfManagerReady → loadDocument:

Entering Worker: on Ready → pdfManagerReady → loadDocument

// Source: src/core/worker.js (closure inside createDocumentHandler)
async function loadDocument(recoveryMode) {
  await pdfManager.initDocument(recoveryMode);

  const isPureXfa = await pdfManager.ensureDoc('isPureXfa');
  if (isPureXfa) {
    const task = new WorkerTask('loadXfaResources');
    startWorkerTask(task);
    await pdfManager.ensureDoc('loadXfaResources', [handler, task]);
    finishWorkerTask(task);
  }

  const [numPages, fingerprints] = await Promise.all([
    pdfManager.ensureDoc('numPages'),
    pdfManager.ensureDoc('fingerprints'),
  ]);

  const htmlForXfa = isPureXfa ? await pdfManager.ensureDoc('htmlForXfa') : null;

  return { numPages, fingerprints, htmlForXfa };
}

Inside initDocument (inherited from BasePdfManager), PDF.js performs a series of integrity checks — parse the header, parse the cross-reference table, parse the document, verify the first and last page load correctly. We won't go into the details here; that will be the topic of a future article.

Once all checks pass, onSuccess is called, which sends the document metadata back to main:

function onSuccess(doc) {
  ensureNotTerminated();
  handler.send('GetDoc', { pdfInfo: doc });
}

Milestone ✅ Ready complete: Worker initializes the PdfManager, probes network capabilities (range / streaming) via fetch, creates either NetworkPdfManager or LocalPdfManager, runs document integrity checks, and sends document metadata back to main with the GetDoc message.

Worker → main: `GetDoc`

Entering main: on GetDoc

messageHandler.on('GetDoc', ({ pdfInfo }) => {
  this.pagesMapper.pagesNumber = pdfInfo.numPages;
  this._numPages = pdfInfo.numPages;
  this._htmlForXfa = pdfInfo.htmlForXfa;
  delete pdfInfo.htmlForXfa;
  loadingTask._capability.resolve(new PDFDocumentProxy(pdfInfo, this));
});

Main stores the document metadata, creates a PDFDocumentProxy — the Display-layer facade for the document — and resolves loadingTask.promise.

Milestone ✅ GetDoc complete: main receives document metadata, creates PDFDocumentProxy and resolves loadingTask.promise. The getDocument call chain is fully resolved.

At this point getDocument returns, and the caller receives a PDFDocumentProxy.

The `getPage` Method

From our demo code:

const loadingTask = pdfjsLib.getDocument({ url: '...' });
const pdf = await loadingTask.promise;
const page = await pdf.getPage(1);

pdf is a PDFDocumentProxy instance, so pdf.getPage(1) calls PDFDocumentProxy.getPage.

Entering main: PDFDocumentProxy.getPage

// Source: src/display/api.js
getPage(pageNumber) {
  return this._transport.getPage(pageNumber);
}

It delegates to WorkerTransport.getPage:

Entering main: PDFDocumentProxy.getPage → WorkerTransport.getPage

// Source: src/display/api.js
getPage(pageNumber) {
  if (
    !Number.isInteger(pageNumber) ||
    pageNumber <= 0 ||
    pageNumber > this.pagesMapper.pagesNumber
  ) {
    return Promise.reject(new Error("Invalid page request."));
  }
  const pageIndex = pageNumber - 1;
  const newPageIndex = this.pagesMapper.getPageId(pageNumber) - 1;

  const cachedPromise = this.#pagePromises.get(pageIndex);
  if (cachedPromise) {
    return cachedPromise;
  }
  const promise = this.messageHandler
    .sendWithPromise("GetPage", { pageIndex: newPageIndex })
    .then(pageInfo => {
      if (this.destroyed) { throw new Error("Transport destroyed"); }
      if (pageInfo.refStr) {
        this.#pageRefCache.set(pageInfo.refStr, newPageIndex);
      }

      const page = new PDFPageProxy(
        pageIndex, pageInfo, this, this.pagesMapper, this._params.pdfBug
      );
      this.#pageCache.set(pageIndex, page);
      return page;
    });
  this.#pagePromises.set(pageIndex, promise);
  return promise;
}

After validating the page number and checking an in-flight promise cache, main sends the GetPage message to the worker.

main → Worker: `GetPage`

Entering Worker: on GetPage

handler.on('GetPage', async function ({ pageIndex }) {
  const page = await pdfManager.getPage(pageIndex);

  const [rotate, ref, userUnit, view] = await Promise.all([
    pdfManager.ensure(page, 'rotate'),
    pdfManager.ensure(page, 'ref'),
    pdfManager.ensure(page, 'userUnit'),
    pdfManager.ensure(page, 'view'),
  ]);
  return { rotate, ref, refStr: ref?.toString() ?? null, userUnit, view };
});

This calls pdfManager.getPage, which goes through BasePdfManager.getPage:

getPage(pageIndex) {
  return this.pdfDocument.getPage(pageIndex);
}

Which lands in PDFDocument.getPage:

Entering Worker: on GetPage → pdfManager.getPage → PDFDocument.getPage

// Source: src/core/document.js
getPage(pageIndex) {
  const cachedPromise = this.#pagePromises.get(pageIndex);
  if (cachedPromise) {
    return cachedPromise;
  }
  const { catalog, linearization, xfaFactory } = this;

  let promise;
  if (xfaFactory) {
    promise = Promise.resolve([Dict.empty, null]);
  } else if (linearization?.pageFirst === pageIndex) {
    promise = this.#getLinearizationPage(pageIndex);
  } else {
    promise = catalog.getPageDict(pageIndex);
  }
  promise = promise.then(
    ([pageDict, ref]) =>
      new Page({
        pdfManager: this.pdfManager,
        xref: this.xref,
        pageIndex,
        pageDict,
        ref,
        globalIdFactory: this._globalIdFactory,
        fontCache: catalog.fontCache,
        builtInCMapCache: catalog.builtInCMapCache,
        standardFontDataCache: catalog.standardFontDataCache,
        globalColorSpaceCache: catalog.globalColorSpaceCache,
        globalImageCache: catalog.globalImageCache,
        systemFontCache: catalog.systemFontCache,
        nonBlendModesSet: catalog.nonBlendModesSet,
        xfaFactory,
      })
  );

  this.#pagePromises.set(pageIndex, promise);
  return promise;
}

This is where PDF.js actually fetches and parses the PDF data for a given page, and constructs a Page instance. We won't go into the deep PDF parsing logic here — that will get its own article.

Back on the main side, WorkerTransport.getPage (code shown above) receives the pageInfo payload and wraps it in a PDFPageProxy, storing it in the page cache and returning it to the caller.

Milestone ✅ GetPage complete: main sends GetPage → Worker retrieves the Page instance from PDFDocument and extracts rotate / view / ref / userUnit → main receives pageInfo, wraps it in PDFPageProxy, and returns it.

Summary

In this article we traced the complete execution paths of getDocument and getPage:

getDocument → creates a PDFDocumentLoadingTask, spins up a Worker and completes the test / ready / test handshake, sends GetDocRequest to obtain a document-scoped message channel, sends Ready to kick off loading. The Worker probes network capability via fetch, creates NetworkPdfManager or LocalPdfManager, validates the document, and replies with GetDoc. Main receives metadata and resolves with a PDFDocumentProxy.
getPage → validates the page number, sends GetPage to the Worker. The Worker resolves the page's PDF dictionary and constructs a Page instance, extracting rotate / view / ref / userUnit. Main wraps the response in a PDFPageProxy and returns it.

At the end of both calls, our demo code has everything it needs:

const loadingTask = pdfjsLib.getDocument({
  url: 'https://assets.streampdf.com/PDF32000_2008.pdf',
});
const pdf = await loadingTask.promise;
const page = await pdf.getPage(1);

We end up holding a PDFPageProxy, which is the foundation for everything that comes next — viewport calculation, rendering to canvas, text extraction, annotations, and more.

Notice we've deliberately stayed at the top of the architecture. Before diving into PDF-level parsing (lexer, XRef table, page dictionary, operators), you need this high-level mental model of how data flows between main and Worker. If you stick with this series, you'll gain both a deep understanding of PDF.js internals and, by extension, a solid grasp of the PDF specification itself.

In the next article we'll move into viewport computation and rendering.

PDF.js Deep Dive 1: The Architecture of PDF.js

StreamPDF — Wed, 21 Oct 2026 13:00:00 +0000

Introduction

This is the first article in the PDF.js Deep Dive series, covering the architecture design of PDF.js.

The analysis in this series is based on the PDF.js v6.3.289 source code.

What is a PDF

Portable Document Format (PDF), standardized as ISO 32000, is a file format developed by Adobe in 1993 used to present documents, including text formatting and images, in a manner independent of application software, hardware, and operating systems. Based on the PostScript language, a PDF file encapsulates a complete description of a fixed-layout document, including the text, fonts, vector graphics, raster images and other information needed to display it.

PDF has its roots in "The Camelot Project" initiated by Adobe co-founder John Warnock in 1991. PDF was standardized as ISO 32000 in 2008. It is maintained by ISO TC 171 SC 2 WG8, of which the PDF Association is the committee manager. The last edition as ISO 32000-2:2020 was published in December 2020.

From Wikipedia: https://en.wikipedia.org/wiki/PDF

It is a file format that does not depend on any particular runtime implementation: a document can be displayed consistently in every environment. In practice, of course, it is the parser and renderer that absorb the differences between environments. It is similar to a high-level language such as Java — the same code runs anywhere, and the runtime translates it for each platform.

This is also the biggest difference from formats such as Word and HTML, which display differently in different environments. HTML in particular is designed to provide different experiences in different environments.

What is PDF.js

A general-purpose PDF parsing and rendering platform built on web standards.

It parses and executes the instructions inside a PDF file, then renders the result on the web.

This series goes deep inside PDF.js, and just as deep inside the PDF specification, ISO 32000. By the time you finish it, you will have both breadth and depth of understanding of the PDF file format.

The layered design of PDF.js

PDF.js divides the whole framework into three layers:

Core layer — parses and interprets the binary PDF file. This layer is the foundation of everything above it. Its APIs are not covered by the versioning policy and may change at any time.
Display layer (API) — sits on top of the core layer and provides easier-to-use APIs for rendering PDF pages and reading other information from the document. Version numbers are based on this layer.
Viewer layer — built on top of the display layer: the default PDF viewer UI shipped with Firefox.

Let's look at a demo and trace how the code executes. Our demo is, in effect, a custom viewer layer.

First, import the PDF.js resources:

import * as pdfjsLib from 'https://cdn.jsdelivr.net/npm/pdfjs-dist@6.3.289/build/pdf.min.mjs';
pdfjsLib.GlobalWorkerOptions.workerSrc =
  'https://cdn.jsdelivr.net/npm/pdfjs-dist@6.3.289/build/pdf.worker.min.mjs';

Then call the exposed entry method with the URL of a file:

const loadingTask = pdfjsLib.getDocument({
  url: 'https://assets.streampdf.com/PDF32000_2008.pdf',
});

Stop — let's not render yet. First, look at the call chain of getDocument, which is a display-layer API:

Validate the arguments
Create a Worker
Set up the communication channel between the Worker thread and the main thread
Start fetching the file data, then send a Ready event over the main↔Worker communication channel
After the Ready event, the Worker creates a pdfManager object. This object belongs to the core layer and provides access to core PDF data such as startxref and the cross-reference (xref) table.
Return the task's Promise

Because this is an asynchronous method driven by a Promise, we generally wait for it to finish before continuing:

const pdf = await loadingTask.promise;

When the promise resolves, the data is ready and the document can be rendered.

// Get the render data for the first page
const page = await pdf.getPage(1);
// Get the viewport for the first page
const viewport = page.getViewport({ scale: 0.5 });
// Grab the canvas we will render onto
const canvas = document.getElementById('canvas-id');
const context = canvas.getContext('2d');

// Size the canvas to match the PDF viewport
canvas.width = Math.floor(viewport.width);
canvas.height = Math.floor(viewport.height);
canvas.style.width = Math.floor(viewport.width) + 'px';
canvas.style.height = Math.floor(viewport.height) + 'px';

// Prepare the render parameters
const renderContext = {
  canvasContext: context,
  viewport,
};

// render returns a RenderTask (Promise); await it so the drawing completes
await page.render(renderContext);

getPage, getViewport, and render above are all methods exposed by the display layer; underneath, they call into the core layer.

Note that we are not diving into these methods here — that is the subject of the next article in this series.

Live demo: https://streampdf.com/blog/demos/a-simple-pdf-render-demo.html

Q: Why is the design layered?

A: In one sentence: confine change to a single place. The PDF specification is enormous and the parsing implementation is bound to keep evolving, while the API exposed to users has to stay stable over the long term; layering puts a "stable contract" between the two — the upper layers depend only on the handful of methods the display layer exposes, so no matter how the code below is refactored, optimized, or even rewritten, nothing outside is affected.

Concretely in PDF.js, layering buys four things.

First, contract and versioning: the core layer's APIs are not covered by the versioning policy and may change at any time, and version numbers are defined by the display layer — the unstable implementation is confined to the bottom layer, while the getDocument / getPage / render that users depend on live in the display layer, where the interface stays stable for the long term.

Second, replaceability: each layer can be replaced on its own — the viewer layer can go from Firefox's built-in viewer to the hand-written calling code in our demo, and the core layer can move from a Worker to the fake worker (falling back to the main thread) or even Node, with the display layer's calling code completely unchanged.

Third, performance and isolation: the core layer runs in a Worker thread, so CPU-heavy parsing never blocks the main-thread UI; layering makes that thread boundary explicit — layers talk only by passing messages through MessageHandler, which keeps the interface clean and the boundary clear.

Fourth, testability: the core layer can be tested on its own, with no DOM and no canvas.

As the Java analogy earlier in this article suggests: Java uses a runtime to smooth over platform differences, and PDF.js uses layering to smooth over "the complexity of the specification" — you do not need to know the details of ISO 32000 to parse and render a PDF.

Architecture diagram

Each row in the diagram is one public API call from the demo: the viewer column is the code we write, the display column holds display-layer objects such as PDFDocumentProxy and PDFPageProxy, and the core column runs inside the Worker thread. The horizontal arrows are message round-trips between layers (via MessageHandler), and the vertical arrows show the call order. getViewport is a pure display-layer size calculation that never touches the Worker, so it has no core counterpart; render, on the other hand, needs the core layer to produce an operator list (GetOperatorList), which is why all three columns are present.

Summary

PDF.js opened up the possibility of rendering PDF files on the web, and it has since become the general-purpose tool for doing so. A deep study of PDF.js gives you a deeper understanding of the PDF specification — you get to read the spec through a working implementation, instead of grinding through the dry specification document directly.

PDF.js's distinctive three-layer design lets developers replace each layer independently. It also supports unique performance techniques such as streaming requests and range requests. I learned a great deal from PDF.js when founding the StreamPDF project — thanks to everyone who has participated in the project.

Next in the series: we will go deep into getDocument and getPage to see exactly what happens in the core layer. It will be a genuinely fascinating logical challenge. See you in the next article.

DEV Community: StreamPDF

PDF.js Deep Dive 2: getDocument & getPage

Introduction

The getDocument Method

Step 1: Create the loading task and global ID generator

Step 2: Process user parameters

Step 3: Create the Worker

Worker ↔ main handshake

main → Worker: GetDocRequest

main → Worker: Ready

Worker → main: GetDoc

The getPage Method

main → Worker: GetPage

Summary

PDF.js Deep Dive 1: The Architecture of PDF.js

Introduction

What is a PDF

What is PDF.js

The layered design of PDF.js

Architecture diagram

Summary

The `getDocument` Method

main → Worker: `GetDocRequest`

main → Worker: `Ready`

Worker → main: `GetDoc`

The `getPage` Method

main → Worker: `GetPage`