Troubleshoot Embedded Demo Playback

Common mistakes

The bundle was never extracted

If you point the player at the ZIP file URL, playback will fail.

Export the demo, unzip the bundle, and host the extracted files as normal static assets first.

The baseUrl points to the wrong place

baseUrl should point to the folder containing manifest.json, not to the file itself.

For example, if this URL works:

https://example.com/demo/manifest.json

then the correct baseUrl is:

https://example.com/demo/

The exported structure was changed

If you flatten the export, rename files, or move directories, the player may no longer be able to resolve the bundle correctly.

Keep the exported structure intact, including:

• manifest.json
• steps/
• assets/
• optional i18n/

The player stylesheet was not imported

For now, styles cannot be reliably imported by the player alone, we are working to fix this and provide you the best possible experience.

Import the public stylesheet in your app before rendering the player:

import '@pokedemo/player/style.css'

The player is rendered on the server

If you are using Nuxt or Next.js, make sure the player runs only on the client.

Use ClientOnly, a client-only component, or a client component depending on your framework.

Browser and runtime limits

The player requires a modern browser environment. Playback may fail in older browsers or environments that do not support the required web platform features.

Hosting checks

If something is broken, verify these first:

• manifest.json is reachable at your baseUrl
• the steps/ directory is accessible
• the assets/ directory is accessible
• the host is not rewriting file requests
• cross-origin hosting still allows the browser to fetch the files normally

If localized content is present, also verify i18n/ is accessible.