|
| 1 | +# Initiate (standard middleware) |
| 2 | + |
| 3 | +Serve a devframe from inside any app that can mount a catch-all route: `initDevframe(def, { base })` returns a live instance whose `.handler` — a web-standard `(request: Request) => Promise<Response>` — carries the whole surface (the SPA, `__connection.json` discovery, the WebSocket RPC endpoint, the auth gate, and the optional MCP route) under one mount base. |
| 4 | + |
| 5 | +```ts |
| 6 | +import { initDevframe } from 'devframe/initiate' |
| 7 | +import myDevframe from './devframe' |
| 8 | + |
| 9 | +const devtools = initDevframe(myDevframe, { base: '/__my-tool/', key: 'my-tool' }) |
| 10 | +// devtools.base, devtools.handler, devtools.nodeMiddleware, devtools.websocket, |
| 11 | +// devtools.ready, devtools.context, devtools.connectionMeta(), devtools.close() |
| 12 | +``` |
| 13 | + |
| 14 | +`base` is required, so the mount path is explicit at the call site — pass the conventional `resolveBasePath(def, 'hosted')` (i.e. `def.basePath ?? /__<id>/`) if you don't want to pick one. The instance echoes the normalized value back as `devtools.base`, so route guards and middleware reference it instead of repeating the string. The factory is synchronous and initializes eagerly; `handler`/`nodeMiddleware` await readiness internally, so hosts never race the boot. |
| 15 | + |
| 16 | +## Mount the handler |
| 17 | + |
| 18 | +::: code-group |
| 19 | + |
| 20 | +```ts [Vite] |
| 21 | +import { initDevframe } from 'devframe/initiate' |
| 22 | +// vite.config.ts — connect-style middleware + Vite's own server for the socket |
| 23 | +import { defineConfig } from 'vite' |
| 24 | +import myDevframe from './devframe' |
| 25 | + |
| 26 | +export default defineConfig({ |
| 27 | + plugins: [{ |
| 28 | + name: 'my-tool', |
| 29 | + apply: 'serve', |
| 30 | + configureServer(server) { |
| 31 | + const devtools = initDevframe(myDevframe, { |
| 32 | + base: '/__my-tool/', |
| 33 | + key: 'my-tool', |
| 34 | + server: server.httpServer ?? undefined, |
| 35 | + }) |
| 36 | + server.middlewares.use(devtools.nodeMiddleware) |
| 37 | + }, |
| 38 | + }], |
| 39 | +}) |
| 40 | +``` |
| 41 | + |
| 42 | +```ts [Nitro] |
| 43 | +// routes/__my-tool/[...path].ts — plus routes/__my-tool/index.ts (same body) |
| 44 | +// for the namespace root, since a catch-all doesn't match its own empty path. |
| 45 | +import { defineHandler } from 'nitro' |
| 46 | +import { devtools } from '../../devtools' |
| 47 | + |
| 48 | +export default defineHandler(event => devtools.handler(event.req)) |
| 49 | +``` |
| 50 | + |
| 51 | +```ts [Hono] |
| 52 | +// server.ts — the same file runs on Node and Bun |
| 53 | +import { Hono } from 'hono' |
| 54 | +import { devtools } from './devtools' |
| 55 | + |
| 56 | +const app = new Hono() |
| 57 | +app.all('/__my-tool/*', c => devtools.handler(c.req.raw, c.env)) |
| 58 | +``` |
| 59 | + |
| 60 | +```ts [Next.js] |
| 61 | +import { initDevframe } from 'devframe/initiate' |
| 62 | +// app/%5F_my-tool/[[...path]]/route.ts — Next reserves `_`-prefixed |
| 63 | +// folders, so the segment is URL-encoded (`%5F_` decodes to `__`). |
| 64 | +import myDevframe from '@/devframe' |
| 65 | + |
| 66 | +export const runtime = 'nodejs' |
| 67 | +export const dynamic = 'force-dynamic' |
| 68 | + |
| 69 | +const devtools = initDevframe(myDevframe, { base: '/__my-tool/', key: 'my-tool' }) |
| 70 | +export const GET = devtools.handler |
| 71 | +``` |
| 72 | + |
| 73 | +```ts [Nuxt] |
| 74 | +// server/middleware/devtools.ts |
| 75 | +import { devtools } from '../devtools' |
| 76 | + |
| 77 | +export default defineEventHandler((event) => { |
| 78 | + const { pathname } = new URL(toWebRequest(event).url) |
| 79 | + // `devtools.base` is the normalized mount base — no repeated string. |
| 80 | + if (pathname.startsWith(devtools.base) || pathname === devtools.base.slice(0, -1)) |
| 81 | + return devtools.handler(toWebRequest(event)) |
| 82 | +}) |
| 83 | +``` |
| 84 | + |
| 85 | +```ts [SvelteKit] |
| 86 | +// src/routes/%5F_my-tool/[...path]/+server.ts |
| 87 | +import myDevframe from '$lib/devframe' |
| 88 | +import { initDevframe } from 'devframe/initiate' |
| 89 | + |
| 90 | +const devtools = initDevframe(myDevframe, { base: '/__my-tool/', key: 'my-tool' }) |
| 91 | +export const GET = ({ request }) => devtools.handler(request) |
| 92 | +``` |
| 93 | + |
| 94 | +::: |
| 95 | + |
| 96 | +For frameworks with dev-time module reloading (Next, Nitro, SvelteKit), always set `key` — a re-evaluation returns the live instance instead of leaking WebSocket servers (`DF0053` reports an intentional replacement when the options changed). |
| 97 | + |
| 98 | +## The WebSocket binding |
| 99 | + |
| 100 | +Fetch handlers hand over `Request`s, so the RPC socket needs its own binding. The instance resolves it in precedence order and advertises the result in `__connection.json` — the browser client follows whatever is advertised: |
| 101 | + |
| 102 | +1. **`ws.port`** — an explicit side-car port. |
| 103 | +2. **`server`** — share the host's `node:http` server; the upgrade binds at `<base>__ws`. Zero extra ports, and the socket follows the app through proxies and HTTPS. |
| 104 | +3. **`ws.url` alone** — advertise an external endpoint verbatim; the server behind that URL owns the transport (wire the instance's `context` into your own server with `startHttpAndWs`). Combined with `server`/`ws.port`, `ws.url` overrides only the advertisement — the tunnel pattern. |
| 105 | +4. **Bun** — same-origin fetch upgrades: pass the `Bun.serve` server as `handler`'s second argument and wire `Bun.serve({ websocket: devtools.websocket })`. |
| 106 | +5. **Default** — an eager side-car on a free port, started at init so the meta is stable from the first request. |
| 107 | + |
| 108 | +## Auth |
| 109 | + |
| 110 | +The instance **gates by default** — a handler mounted inside an app server is reachable by anything that can open its socket. Devframe's interactive OTP handler is wired automatically and prints its code/magic-link banner once the public origin is known (derived from the first request, or the `origin` option). Pass `auth: false` for a single-user localhost setup, or a `DevframeAuthHandler` for a custom scheme. |
| 111 | + |
| 112 | +## Relation to the other adapters |
| 113 | + |
| 114 | +`createDevServer`, `viteDevBridge`, and `@devframes/next` are assembled from this instance internally — the handler is the one wiring underneath every serving path. To host **many** devframes behind one namespace with shared transport and docks, use the hub's counterpart: [`initHub`](../guide/hub-initiate). |
0 commit comments