Start with the exact error and the smallest document that reproduces it. Run validate(document) before rendering. Each issue has a failing path, a stable code, a severity and a suggested fix.
Installation fails on workspace:*
Install the published package, not a tarball copied directly from the Runstamp monorepo:
pnpm add @runstamp/sdk react react-domPublished packages replace internal workspace:* ranges when packed. If the
SDK registry tarball still contains one, capture pnpm view @runstamp/sdk version,
your lockfile entry, and the full install error, then report it as a packaging
bug.
The deck works in LibreOffice but PowerPoint repairs it
LibreOffice is useful for a quick visual check. It is not the compatibility authority for .pptx. Validate the generated file in desktop Microsoft PowerPoint on Windows or macOS. A clean LibreOffice open does not prove PowerPoint accepts chart XML, relationships, embedded media or content types.
If PowerPoint shows a repair prompt:
- Keep the original generated file; do not save over it.
- Record the Runstamp package versions and operating system.
- Reduce the input while keeping the repair prompt.
- Attach PowerPoint's repair log and the reduced input to the bug report.
Do not suppress validation errors or use LibreOffice success as a release gate.
Fonts look different between preview and PowerPoint
The React viewer uses fonts available in the browser. PowerPoint uses fonts on the machine that opens the deck, unless the file embeds compatible fonts. Load the same web fonts in the viewer, call autoLoadDocumentFonts(document) before local PPTX rendering, and test the exported file on a machine with the intended fonts.
React components fail during server rendering
Import the stylesheet once in your app entry point. Render the
interactive viewer from a Client Component. Keep file generation in a
Node.js server route that uses @runstamp/sdk/react/server. Don't call browser-only
download code during server render.
For Next.js Route Handlers, set:
export const runtime = "nodejs";validate() returns warnings but ok is true
ok means there are no error-severity issues. Warnings flag quality or compatibility risks worth fixing before distribution. Treat errors as render blockers. Decide explicitly whether your workflow allows each warning code.
The downloaded file is empty or named incorrectly
Return the renderer's bytes without JSON encoding, with the PPTX content type:
application/vnd.openxmlformats-officedocument.presentationml.presentation
Set Content-Disposition to an attachment ending in .pptx. In Node.js, keep the returned Uint8Array or Buffer. Don't convert it through UTF-8 text.
Still blocked
Include a minimal input document, exact package and runtime versions, the target Office app and version, validation issues, and the smallest generated file that reproduces the failure. Remove confidential content before sharing.