|
2 | 2 | outline: deep |
3 | 3 | --- |
4 | 4 |
|
5 | | -# Vite Bridge |
| 5 | +# @devframes/vite |
6 | 6 |
|
7 | | -A thin Vite plugin for mounting a devframe inside an existing Vite dev server. Used by [`@devframes/nuxt`](./nuxt) and available for any Vite-based host (Astro, SolidStart, plain Vite apps). |
| 7 | +Two Vite plugins for mounting a devframe inside an existing Vite dev server — `devframeVitePlugin` (static mount) and `devframeViteBridge` (RPC bridge) — plus `devframeVite`, a convenience wrapper that picks between them. Used by [`@devframes/nuxt`](./nuxt) and available for any Vite-based host (Astro, SolidStart, plain Vite apps). |
8 | 8 |
|
9 | | -This sits below the [`vite` adapter](/adapters/vite) on the abstraction ladder: the adapter targets the full Vite DevTools dock; the bridge is the lower-level Vite plugin you reach for when you want a devframe to ride along with an existing app's dev server without the DevTools dock. |
| 9 | +This sits below the [`vite` adapter](/adapters/vite) on the abstraction ladder: the adapter targets the full Vite DevTools dock; these are the lower-level Vite plugins you reach for when you want a devframe to ride along with an existing app's dev server without the DevTools dock. |
10 | 10 |
|
11 | 11 | ```ts |
12 | | -import { viteDevBridge } from '@devframes/vite' |
| 12 | +import { devframeViteBridge, devframeVitePlugin } from '@devframes/vite' |
13 | 13 | import { defineConfig } from 'vite' |
14 | 14 | import devframe from './devframe' |
15 | 15 |
|
16 | 16 | export default defineConfig({ |
17 | | - plugins: [viteDevBridge(devframe)], |
| 17 | + // Statically mounts the built SPA at `/__<id>/` — no RPC server: |
| 18 | + plugins: [devframeVitePlugin(devframe)], |
| 19 | + // Or bridge the RPC/WS backend into this dev server instead — the |
| 20 | + // host app owns the SPA: |
| 21 | + // plugins: [devframeViteBridge(devframe)], |
18 | 22 | }) |
19 | 23 | ``` |
20 | 24 |
|
21 | | -## Modes |
| 25 | +## `devframeVitePlugin` — static mount |
22 | 26 |
|
23 | | -- **Static mount** (default) — mounts `def.cli.distDir` at `options.base` (`/__<id>/` by default). No RPC server. Useful when you only need the SPA bundle served from a known path. |
24 | | -- **Bridge mode** (`devMiddleware: true | {…}`) — skips the static mount; the host app owns the SPA. Devframe spawns a separate RPC + WS server and registers Vite middleware at `<base>__connection.json` so the host-served SPA can discover the WS endpoint. The side-car listens on its own port, so the descriptor carries that port alongside the `/__ws` route. |
| 27 | +Mounts `def.cli.distDir` at `options.base` (`/__<id>/` by default) with SPA fallback. No RPC server is started — useful when you only need the SPA bundle served from a known path. |
25 | 28 |
|
26 | | -To mount the RPC socket onto the Vite server's own port instead of a side-car — so it shares the origin with the app and rides through a proxy — pass Vite's HTTP server to [`initDevframe`](/adapters/initiate) / `initHub` via the `server` option. Devframe binds only its own `<base>__ws` upgrade route and leaves the rest (Vite's HMR socket included) untouched. |
| 29 | +| Option | Default | Description | |
| 30 | +|--------|---------|-------------| |
| 31 | +| `base` | `def.basePath ?? '/__<id>/'` | Mount path inside the Vite dev server. | |
| 32 | + |
| 33 | +## `devframeViteBridge` — RPC bridge |
27 | 34 |
|
28 | | -## Options |
| 35 | +Skips the static mount — the host app owns the SPA. Devframe spawns a separate RPC + WS server and registers Vite middleware at `<base>__connection.json` so the host-served SPA can discover the WS endpoint. The side-car listens on its own port unless it can share Vite's own HTTP server, so the descriptor carries that port alongside the `/__ws` route. |
| 36 | + |
| 37 | +To mount the RPC socket onto the Vite server's own port instead of a side-car — so it shares the origin with the app and rides through a proxy — pass Vite's HTTP server to [`initDevframe`](/adapters/initiate) / `initHub` via the `server` option. Devframe binds only its own `<base>__ws` upgrade route and leaves the rest (Vite's HMR socket included) untouched. |
29 | 38 |
|
30 | 39 | | Option | Default | Description | |
31 | 40 | |--------|---------|-------------| |
32 | 41 | | `base` | `def.basePath ?? '/__<id>/'` | Mount path inside the Vite dev server. | |
33 | | -| `devMiddleware` | `false` | `true` or `{ port?, host?, flags? }` to enable bridge mode. | |
| 42 | +| `port` | share Vite's HTTP server | Pin a side-car port for the RPC socket instead. | |
| 43 | +| `host` | `def.cli?.host ?? 'localhost'` | Bind host for a pinned side-car. | |
| 44 | +| `flags` | — | Forwarded to `def.setup(ctx, { flags })`. | |
| 45 | +| `auth` | gated (interactive OTP) | `false` to opt out for a single-user localhost host, or a `DevframeAuthHandler` for a custom scheme. | |
| 46 | +| `mcp` | `def.cli?.mcp` | `true` or `McpRouteOptions` to expose the route-based MCP server at `<base>__mcp`. | |
| 47 | + |
| 48 | +`port` / `host` / `flags` mirror [`createDevServer`](/adapters/dev)'s options of the same name. |
| 49 | + |
| 50 | +## `devframeVite` — convenience wrapper |
34 | 51 |
|
35 | | -When `devMiddleware` is an object, the inner fields mirror [`createDevServer`](/adapters/dev) — `port` pins the WS server port, `host` sets the bind host, and `flags` is forwarded to `def.setup(ctx, { flags })`. |
| 52 | +`devframeVite(def, { bridge, ...bridgeOptions })` forwards to `devframeViteBridge` when `bridge: true`, or `devframeVitePlugin` otherwise — handy when a single call site needs to switch between the two modes. Reach for the two plugins directly when a devframe needs both mounted at once (e.g. a bridge for RPC alongside a static mount serving its own bundled UI, as the built-in `terminals`/`code-server` plugins do). |
0 commit comments