OPF
DocsIntegration

Website, editor and Node starters

Download a complete project, install its pinned dependencies, and run it locally. No provider account or hosted API.

New to OPF? Your first deck in ten minutes uses a fourth, smaller starter: a brief, a five-slide deck and the validate, PNG and PPTX commands.

Node 22 or later (every package declares engines.node >=22); this site and the starters are tested on Node 24. Each ZIP includes its package manifest, a real deck, source files and a README. Run the commands inside the extracted directory. Commit the generated package-lock.json to keep later installs reproducible.

Since OPF 0.16 the renderer's PNG and PDF converters (@resvg/resvg-js, sharp, pdf-lib) and its font packages are optional peers. Each starter's package.json lists the ones it uses, pinned: the PNG converter, sharp for pictures, and the Roboto font packages (website and editor: the Office substitutes too). Add pdf-lib only for raster PDFs. A missing one fails with converter-missing or names the package and the install command.

Choose the package and runtime

Start with the runnable project below. Use these contracts when adding behavior; the CLI and agent setup stay in For agents.

TaskPackage and runtimeExact reference
Read, validate and convert filesCore: file APIs in Node; schemas and pure helpers in browsersNode files, results and errors
Render SVG, PNG or PDFRenderer: browser SVG/export entries; Node convertersEntries and optional peers
Export or import PowerPointPPTX: Node and browsersExport, import and signals types
Embed an editable canvasEditor: headless session and browser controlsEmbed and host lifecycle; session types
Run a terminal or agent workflowCLI: NodeCommands and typed reports
Use themes, layouts and fontsGallery: canonical catalog records for any hostCatalog registration and ownership

Core convert returns { files, findings } and typed errors. Direct renderer/PPTX calls return SVG or bytes and report onDiagnostic; fromPptx with signals: true returns { presentation, signals }. Inspect those results before replacing or publishing a document. The editor can refuse a draft commit; keep the draft until it is fixed or explicitly canceled.

A website with presentation downloads

Download the website starter. It embeds two slides with thumbnails and presentation mode, and offers PowerPoint, PDF and original OPF downloads. The export step generates those files locally before the site runs.

In website/
npm install
npm run fonts
npm run export
npm run dev

Open the localhost URL printed by Vite. The status becomes Ready after the deck and its fonts load. Vite processes npm imports in this HTML; opening the file directly or serving it without a bundler cannot resolve the package import. Replace public/deck.opf.json with your deck, then rerun the export step.

Website source
index.html
<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>OPF website starter</title><link rel="stylesheet" href="/style.css"></head>
<body>
<h1>Quarterly Review</h1>
<p id="status" role="status">Loading presentation…</p>
<opf-deck src="/deck.opf.json" fonts="/opf-fonts/" thumbnails present></opf-deck>
<p><a href="/downloads/deck.pptx" download>Download PowerPoint</a><a href="/downloads/deck.pdf" download>Download PDF</a><a href="/deck.opf.json" download>Download OPF source</a></p>
<script type="module" src="/main.js"></script>
</body>
</html>

The component exposes ready, slidechange, presentstart, presentend and error. Its JSON source and font files are served from the same origin. Keep the generated font directory and its license notices in your static build.

An editor embedded in your app

Download the editor starter. The page is one <opf-editor layout="full"> tag: the source pane, the slide, the slide row and a toolbar with the deck's name (edited in place), Undo and Redo, Find, Design, Review, Export, Present and Expand. On a narrow screen the items that do not fit move into the toolbar's ⋯ menu. main.js adds PowerPoint to the Export menu, a Save button that downloads the deck, and a prompt before the page closes with unsaved changes. One fonts handle serves the preview and every export.

In editor/
npm install
npm run fonts
npm run dev

After Ready, click slide text to edit or rename the deck in the toolbar. Cmd/Ctrl+Enter commits and Escape cancels; Cmd/Ctrl+S inside the editor saves. The host owns persistence, authentication and collaboration: replace the opf-save listener with your own storage and call markSaved(). PowerPoint loads on the export click.

Other presets: layout="embed" is the slide under a compact bar (the deck's name, Undo and Redo, the counter, Design, Expand and Present) for a page that shows a deck, canvas adds the slide row and viewer is read-only. The toolbar attribute picks the items:

index.html
<opf-editor layout="embed" src="/deck.opf.json" fonts="/opf-fonts/"
  toolbar="title,history,counter,spacer,expand,more"></opf-editor>
Editor page
index.html
<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>OPF editor starter</title><link rel="stylesheet" href="/style.css"></head>
<body>
<h1>OPF editor starter</h1><p id="status" role="status">Loading editor…</p>
<!-- The whole editor as one tag: the source pane, the slide, the slide row and a toolbar (the deck's name, Undo and Redo, Find, Design,
     Review, Export, Present, Expand), whose items move into its ⋯ menu on a narrow screen. Fonts come from public/opf-fonts (npm run fonts). -->
<opf-editor id="editor" layout="full" src="/deck.opf.json" fonts="/opf-fonts/">
  <noscript>This editor needs JavaScript. <a href="/deck.opf.json">Download the deck</a>.</noscript>
</opf-editor>
<script type="module" src="/main.js"></script>
</body>
</html>
Editor source
main.js
import '@openpresentation/opf-editor/styles.css';
import '@openpresentation/opf-editor/element/define';
import { loadPreviewFonts } from '@openpresentation/opf-render/preview-fonts';
const status = document.querySelector('#status');
const element = document.querySelector('#editor');
function save(bytes, type, name) {
  const url = URL.createObjectURL(new Blob([bytes], { type }));
  const link = document.createElement('a');
  link.href = url; link.download = name; link.click();
  setTimeout(() => URL.revokeObjectURL(url), 10000);
}
// One fonts handle for the slide, the browser exports and PowerPoint, from this site's own public/opf-fonts.
const fonts = loadPreviewFonts('/opf-fonts/');
element.fonts = fonts;
// More createOpfEditor options: PowerPoint in the Export menu (the converter is the page's, loaded on demand), a Save button in the
// toolbar, and the browser asks before the page closes while there are unsaved changes.
element.options = {
  guardUnload: true,
  export: {
    async exportPptx(deck) {
      const handle = await fonts;
      await handle.ensure(deck);
      const { toPptx } = await import('@openpresentation/opf-pptx');
      const warnings = [];
      const bytes = await toPptx(deck, { fonts: handle, onDiagnostic: item => warnings.push(item.code + ': ' + item.message) });
      return { bytes, warnings };
    },
  },
  actions: [{ id: 'save', label: 'Save OPF', primary: true, enabled: () => Boolean(element.editor?.dirty), run: () => element.editor?.save() }],
};
// Save (the button, or Ctrl/Cmd+S inside the editor) downloads the deck; replace this with your own storage.
element.addEventListener('opf-save', ({ detail }) => {
  if (detail.draft) { status.textContent = 'The source is not a valid deck yet: nothing was saved.'; return; }
  save(JSON.stringify(detail.document, null, 2), 'application/json', 'deck.opf.json');
  element.editor.markSaved();
  status.textContent = 'OPF saved';
});
element.addEventListener('opf-dirty', ({ detail }) => { status.textContent = detail.dirty ? 'Unsaved changes' : 'All changes saved'; });
element.addEventListener('opf-deck-name', ({ detail }) => { document.title = (detail.name || 'Untitled presentation') + ' · OPF editor starter'; });
element.addEventListener('opf-export', ({ detail }) => { status.textContent = 'Exported ' + detail.fileName + (detail.notes.length ? ': ' + detail.notes.join('; ') : ''); });
element.addEventListener('opf-error', ({ detail }) => { status.textContent = 'Error: ' + detail.message; });
try {
  const editor = await element.ready;
  status.textContent = 'Ready: ' + (editor.getDeckName() || 'Untitled presentation');
} catch (error) {
  status.textContent = 'Startup error: ' + error.message;
}

For your own header, React (<OpfEditor>, useOpfDeckName, useOpfDirty) or Svelte, use createOpfEditor: the chrome guide has each task, styling the chrome lists its classes, tokens and icons, and the editor guide covers structural editing.

A Node export pipeline

Download the Node starter. It validates the source, paginates with the same fonts handle, and writes OPF, SVG, PNG, vector PDF and PowerPoint under output/. The PowerPoint has native text, tables and charts; by default each wrapped text line is its own text box, so edited text does not reflow; the exporter's bodyText: "native" option, or opf convert --body-text native from core 0.22.2, opts in to reflowing bodies (what to expect).

In node/
npm install
npm run export
# Or choose input and output paths:
node export.mjs deck.opf.json output
Node source
export.mjs
import { mkdir, readFile, writeFile } from "node:fs/promises";
import path from "node:path";
import { assertValid } from "@openpresentation/opf";
import { paginate } from "@openpresentation/opf/pagination";
import { loadFonts } from "@openpresentation/opf-render/fonts-node";
import { toPdf, toPng, toSvg } from "@openpresentation/opf-render";
import { toPptx } from "@openpresentation/opf-pptx";

const input = process.argv[2] ?? "deck.opf.json";
const output = process.argv[3] ?? "output";
const deck = JSON.parse(await readFile(input, "utf8"));
assertValid(deck);
// This starter chooses Roboto, covered by base. Load office when your deck requires it.
const fonts = await loadFonts({ pack: "base", presentation: deck, scripts: "auto", embedScriptFonts: true });
const { presentation } = paginate(deck, { fonts });
const svgs = toSvg(presentation, { fonts }); // one SVG per slide
await mkdir(output, { recursive: true });
await writeFile(path.join(output, "deck.opf.json"), JSON.stringify(presentation, null, 2));
await writeFile(path.join(output, "slide-1.svg"), svgs[0]);
await writeFile(path.join(output, "slide-1.png"), await toPng(svgs[0], { fonts }));
await writeFile(path.join(output, "deck.pdf"), await toPdf(svgs, { fonts }));
await writeFile(path.join(output, "deck.pptx"), await toPptx(presentation, { fonts, onDiagnostic: item => console.warn(item.code + ": " + item.message) }));
console.log("Exported " + presentation.slides.length + " slides to " + output);

The starter chooses Roboto, which the base pack covers. Use the Office pack for decks that require its substitutes, and install the renderer’s optional script-font packages for the languages you use before measuring. Standalone SVG exports enableembedScriptFonts: true so their drawn script faces travel with the file. PPTX conversion diagnostics are printed to the terminal.

PPTX names chosen fonts but does not embed their binaries; the viewer needs those fonts. Full provenance restores supported authored semantics when native evidence is unchanged. Mechanical import can normalize fields and unsupported Office features; keep the original OPF as canonical source.

Delivery and hosting

For the browser starters run npm run build, then npm run preview to inspect the production bundle. Serve the generated dist/ from your static host. No upload or deployment is part of these commands.

Measure compressed JavaScript separately from font requests. The interactive renderer includes font measurement and shaping code; loading font faces on demand does not remove that JavaScript cost. Dynamic export imports defer conversion code until requested.

For a content site, generate SVG, PDF and PPTX ahead of time and cache those immutable outputs by deck revision, package versions, render options and font-file hashes. A standalone SVG carries embedded faces and may be large. Multi-slide self-contained HTML can repeat them: render the first slide initially, or supply the exact matching fonts through host-owned CSS for shared delivery.

For on-demand exports, run the Node pipeline in a worker or background job with bounded input size and concurrency, cancellation and a timeout. Reuse a fonts handle per worker. Keep CPU-heavy conversion off the request handler; cache completed results. A container needs the locked packages and pinned fonts, and does not need desktop Office. Choose memory and worker limits from measurements of your own deck sizes, scripts and image assets.