docs(slider): how to open your own app page and route to it in Nuxt

[IgorShevchik]

Closes #356.

From a production incident: the SDK delivered the parameter correctly, the middleware recognised it, and the slider still showed the app's main page — with no error raised by anything. The cause was Nuxt, not the SDK. But the docs are where a developer looks first when a slider shows the wrong screen, and today they cannot tell you that the SDK's half of the job succeeded.

Slider page

What the portal does with each argument — three things that each sent someone down a wrong path:

• the portal re-opens your own registered handler URL, not a portal path. openPath is the one for portal paths, and pointing it at an application page 404s — which reads as "sliders cannot host app pages" and is a frequent wrong turn;
• everything in the argument object arrives as PLACEMENT_OPTIONS, so place is an ordinary call parameter and needs no placement.bind;
• bx24_width below your own mobile breakpoint silently renders the mobile layout.

The Nuxt routing half, stated as a warning because the failure is silent:

A redirect returned from route middleware does not survive the first navigation when the entry route is prerendered. The portal opens the frame with a query string; for a prerendered page Nuxt hydrates on the bare path and then restores the original URL on app:suspense:resolve by assigning router.currentRoute.value directly — bypassing guards, and overwriting the redirect.

Worth stressing that this is not just nuxt generate: nuxt build prerenders anything in nitro.prerender.routes, and with crawlLinks anything reachable by a link. The report measured it served both by nginx and by Nitro — identical failure, so what serves the page is irrelevant.

Includes the onNuxtReady variant, the measured table of where a navigation can be issued from, and the two details that each cost the reporting team a round: compare paths tolerating a trailing slash (a static server serves /app/, the router resolves /app, and a strict !== cancels every redirect), and take the query from location.search rather than to.query.

A troubleshooting checklist for the symptom, since several unrelated causes produce it and none raises an error. Including the point that steps 2–3 reproduce with no portal involved — serve the built app and open /<page>?place=<place>.

Placement page

PLACEMENT_OPTIONS can arrive as a JSON string, with key case not guaranteed across entry points — so options?.place can be undefined with no error, which is the same symptom as the parameter never arriving.

And isSliderMode is derived from PLACEMENT_OPTIONS.IFRAME, so it must not be used to decide whether placement data arrived at all. The original team gated slider diagnostics on it, so the log line went quiet exactly when the data it was diagnosing was missing.

Skill

b24jssdk-frame-ui carries the same guidance plus three anti-patterns, so generated code gets the variant that survives a prerendered route rather than the one that fails silently on it.

The one deliberate debt

The middleware example is built from Nuxt auto-imports and two app-level helpers, none of which exist in the isolated context docs:typecheck-blocks compiles in. It carries @check-ignore with that reason — un-checkable rather than unfixed.

That took the marker count from 50 to 51, one over the warning threshold, so CHECK_IGNORE_WARN_THRESHOLD moves to 51 and records why. The comment on that constant asks for exactly this — raise it deliberately, don't let it creep silently.

Out of scope, raised in the issue rather than dropped

• An SSG variant of the Nuxt example belongs to b24sdk-examples, a different repository.
• Adding placement.option('place') — a parsing accessor that tolerates the JSON-string and key-case variance — is an API change, not documentation, and should be decided on its own. The docs now describe the hazard so an app can defend itself today.

Verification

docs-lint --strict 0/0, docs-typecheck-blocks 153 blocks 0 errors, docs-link-check 0 broken, md-internal-links 0 broken, lint:md clean over 21 files, check-v3-method-refs clean, skills:typecheck passes, docs-lint's own 48 script tests pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01F22e2ft66y7nuBJjzdThBr

---

Generated by Claude Code