Setup

npm install @cloudpdf/engine@next

The engine talks to a CloudPDF server over HTTPS: the managed CloudPDF service, or your own server. It runs in every modern browser and in Node 18 or newer.

Create the engine once#

Create one engine when your app starts and share it everywhere:

// pdf.ts
import { cloudEngine } from '@cloudpdf/engine';
 
export const engine = cloudEngine();

It connects to CloudPDF SaaS; your own server goes in baseUrl (see Options). Creating the engine makes no request. One engine holds any number of open documents, each with its own token. Close each document when you’re done with it (doc.close()), and keep the engine for the life of your app.

Tokens#

Every request carries a token that says who the user is and what they may do. Your backend creates it; the browser never sees your secret key. Most apps pass the token when they open a document:

const doc = await engine.open({ kind: 'token', token: () => fetchDocumentToken(documentId) });

Pass a function rather than a string: the engine calls it for every request, so when your backend hands out short-lived tokens, a long session keeps working. Authentication covers the three ways to open a document and what goes in a token.

Options#

Busy servers#

When the server is busy or restarting, it tells the engine to try again. The engine waits as long as the server asks and retries, up to twice, before the call fails. You don’t need to do anything; onRetry lets you see it happen:

const engine = cloudEngine({
  onRetry: ({ path, code, attempt, waitMs }) => {
    console.debug(`retrying ${path} after ${code} (attempt ${attempt}, waited ${waitMs} ms)`);
  },
});

Only requests the server didn’t apply are retried, so a retry never makes a change twice.