No clean path to mount a devtools-kit devtools.setup plugin (embedded dock) under Nuxt SSR (0.6) #289

Summary

There's no clean path to surface a @vitejs/devtools-kit-based devtool (one that integrates via the Vite plugin.devtools.setup(ctx) hook) inside a Nuxt SSR app on devframe 0.9 / devtools-kit 0.6. The embedded dock silently never loads, and the documented Nuxt integration (@devframes/nuxt/hub) only accepts raw DevframeDefinitions, not kit devtools.setup plugins.

Context

I'm migrating a Vite plugin (a Storybook devtool) from @vitejs/devtools 0.3.x → 0.6.0 (devframe 0.9). It integrates the standard way: a Vite plugin exposing devtools: { setup(ctx) { ctx.docks.register(...); ctx.views.hostStatic(...); ctx.rpc.register(...); ... } }. This works great in plain-Vite SPAs (React/Vue).

What breaks under Nuxt SSR

In 0.3.x the embedded dock reached the browser through Vite's module graph — Nuxt exposed it at /_nuxt/@id/__x00__virtual:vite-devtools-injection, so injecting that import into Nuxt's head made the dock appear.

In 0.6, @vitejs/devtools' injection plugin instead injects a runtime <script type="module" src="/sitelet?url=https%3A%2F%2Fgithub.com%2F__devtools%2Fembedded.js">, and embedded.js (plus /__devtools-client-imports.js) is served by the hub connect middleware mounted on the Vite dev server. Under Nuxt SSR, Nitro owns the request path and does not forward /__devtools/* to Vite's middleware, so all of these return the app's SPA HTML instead of the dock assets:

GET /__devtools/                    -> 200 text/html (Nuxt page, not the dock)
GET /__devtools/embedded.js         -> 200 text/html (Nuxt page, not JS)
GET /__devtools-client-imports.js   -> 200 text/html (Nuxt page)

The old module-graph virtual id is gone (/_nuxt/@id/__x00__virtual:vite-devtools-injection -> 404), so the previous mechanism no longer works either. Net effect: the in-page/client side works, but the embedded dock UI never loads in Nuxt SSR.

Why @devframes/nuxt doesn't cleanly cover this

@devframes/nuxt/hub is exactly the right shape (wires @devframes/vite/hub into Nuxt's Vite server and injects <base>embedded.js), but viteDevframeHub mounts raw DevframeDefinitions (devframes: InitHubOptions['devframes']) — it does not consume @vitejs/devtools-kit plugin.devtools.setup(ctx) plugins. So a kit-based devtool would have to be re-expressed as a standalone defineDevframe() definition and mounted a second, different way just for Nuxt, in addition to the kit path it already uses under @vitejs/devtools everywhere else.

Asks / questions

1. Is there (or can there be) a supported way to mount a kit devtools.setup(ctx) plugin into a Nuxt SSR app so its dock loads — e.g. @vitejs/devtools documenting a Nitro dev proxy for /__devtools/* (+ the RPC WebSocket), or a kit→DevframeDefinition adapter usable with @devframes/nuxt/hub?
2. If the intended answer is "re-express as defineDevframe() and use @devframes/nuxt/hub (or @nuxt/devtools)", could the migration docs call this out explicitly? The 0.6 change from module-graph injection to middleware-served embedded.js is an easy silent-break for SSR hosts.

Minor, possibly related

A DF8111 warning ("dock declares the bare-specifier client script …, but this host advertises no client-module resolution") fires even in plain Vite, where the dock works fine. If that's expected under Vite (client modules resolve via /@id/{specifier}), the warning may be a false positive worth gating; if not, it may hint at the same client-script-resolution gap on non-Vite hosts.

Environment: @vitejs/devtools 0.6.0, @vitejs/devtools-kit 0.6.0, devframe/@devframes/hub 0.9.5, Vite 8, Nuxt 4.