Installation

The engine is a single package. Install it in the app that will talk to your CloudPDF server — typically your frontend, but it also runs in Node.

npm install @cloudpdf/engine@next

Requirements#

A @cloudpdf/server endpoint — self-hosted or CloudPDF SaaS. The engine is a thin HTTP client; it needs a server to talk to.
A fetch implementation. All evergreen browsers and Node 18+ ship one globally. On older Node you can pass your own (for example undici) via the fetch option.
Document-scoped JWTs, minted by your backend. See Authentication.

Create an engine#

createCloudEngine returns an Engine bound to your server’s base URL. The token may be a string or a function that returns a fresh token, so you can rotate credentials without re-creating the engine.

import { createCloudEngine } from '@cloudpdf/engine';
 
const engine = createCloudEngine({
  baseUrl: 'https://pdf.your-app.com',
  // String, or a (possibly async) factory called on every request:
  token: async () => fetchTenantToken(),
});

Options#

Option	Type	Notes
`baseUrl`	`string`	Origin of your `@cloudpdf/server` deployment. A trailing slash is trimmed for you.
`token`	`string \| () => string \| Promise<string>`	Optional. Bearer token sent as `Authorization: Bearer …`. Omit it for the public-share flow, where each `open({ kind: 'token' })` carries its own token.
`fetch`	`typeof fetch`	Optional. Replace the global `fetch` (e.g. `undici` in Node tests).

Prefer a token factory over a static string. The engine calls it on every request, so short-lived tokens refresh transparently as your backend rotates them.

Verify the install#

Open a document by id and read its metadata. If this resolves, your engine, base URL, and token are wired up correctly.

const doc = await engine.open({ kind: 'id', id: 'doc_proposal_2026' });
const meta = await doc.metadata.read();
 
console.log(meta.title);
 
await doc.close();

Next, head to the Quick start to render a page.