@devframes/next 0.8.1 → 0.9.0-beta.1

package/dist/client.d.mts

@@ -1,6 +1,6 @@
 import { DevframeConnectionStatus, DevframeRpcClient } from "devframe/client";
 import { ReactNode } from "react";
-import { ConnectionMeta } from "devframe/types";
+import { ConnectionMeta } from "devframe";
 //#region src/client.d.ts
 interface DevframeRpcState {
   /** The connected client, or `null` while the initial connect is in flight. */

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { CreateDevServerOptions } from "devframe/adapters/dev";
-import { ConnectionMeta, DevframeDefinition, DevframeHost, DevframeNodeContext, DevframeStorageScope } from "devframe/types";
+import { InitDevframeOptions } from "devframe/initiate";
+import { ConnectionMeta, DevframeDefinition, DevframeHost, DevframeNodeContext, DevframeStorageScope } from "devframe";
 //#region src/config.d.ts
 /**
  * Minimal shape of the bits of `next.config` this helper reads/writes, so the
@@ -45,34 +45,40 @@ interface CreateDevframeNextHandlerOptions {
   /** Flag bag forwarded to `def.setup(ctx, { flags })`. */
   flags?: Record<string, unknown>;
   /**
-   * Whether the side-car runs its own auth gate. **Gates by default** (defers
-   * to `createDevServer` — devframe's interactive OTP unless the definition's
-   * `cli.auth` opts out), so the side-car socket isn't silently reachable by
-   * anything that can open it. Pass `false` to opt out for a single-user
-   * localhost host, or a handler for a custom scheme.
+   * Whether the side-car runs its own auth gate. **Gates by default**
+   * (devframe's interactive OTP unless the definition's `cli.auth` opts
+   * out), so the side-car socket isn't silently reachable by anything that
+   * can open it. Pass `false` to opt out for a single-user localhost host,
+   * or a handler for a custom scheme.
    */
-  auth?: CreateDevServerOptions['auth'];
+  auth?: InitDevframeOptions['auth'];
   /** Origin the Next app is reachable at, for docks needing an absolute URL. */
   resolveOrigin?: () => string;
   /** Override where persisted devframe state lives (defaults under the cwd / home). */
   getStorageDir?: (scope: DevframeStorageScope) => string;
   /**
-   * Expose the side-car's route-based MCP server (Streamable-HTTP) and
-   * advertise it in the handler's `__connection.json`. Forwarded to
-   * `createDevServer`: overrides `def.cli?.mcp`, `undefined` falls through to
-   * it, `false` disables the route regardless. The endpoint lives on the
-   * side-car's own port, so the advertised meta carries `{ port, path }`.
+   * Expose the route-based MCP server (Streamable-HTTP) at `<base>__mcp` —
+   * on the Next app's own origin, through the same catch-all route as the
+   * SPA — and advertise it in the handler's `__connection.json`. Overrides
+   * `def.cli?.mcp`, `undefined` falls through to it, `false` disables the
+   * route regardless.
    *
    * @experimental
    */
-  mcp?: CreateDevServerOptions['mcp'];
+  mcp?: InitDevframeOptions['mcp'];
+  /**
+   * Memoization key for the handler. Next re-runs route modules across
+   * dev-time reloads; the key makes a re-run return the live handler instead
+   * of leaking side-car servers. Default: `@devframes/next:<def.id>:<base>`.
+   */
+  key?: string;
 }
 interface DevframeNextHandler {
   /**
    * WHATWG-`fetch` handler for the catch-all App Router route. Serves the
-   * plugin's built SPA at `base` and answers `<base>/__connection.json` with
-   * the side-car WS endpoint. Awaits {@link DevframeNextHandler.ready} so the
-   * first request doesn't race the server boot.
+   * plugin's built SPA at `base` and answers `<base>__connection.json` with
+   * the RPC endpoint. Awaits {@link DevframeNextHandler.ready} so the first
+   * request doesn't race the server boot.
    */
   fetch: (request: Request) => Promise<Response>;
   /** Resolves once the side-car RPC/WS server is listening. */
@@ -81,16 +87,13 @@ interface DevframeNextHandler {
   close: () => Promise<void>;
 }
 /**
- * Host a **single** devframe from a Next.js App Router app — the convenience
- * wrapper over {@link createDevframeNextHost} for the common case of mounting
- * one plugin (the Next counterpart to `viteDevBridge`'s bridge mode).
- *
- * It statically serves `def.cli.distDir` at `base` through the Next route and
- * starts a side-car RPC/WS dev server (via `createDevServer` in bridge mode) on
- * its own port, advertising that endpoint at `<base>/__connection.json` so the
- * SPA's `connectDevframe()` can dial back in.
+ * Host a **single** devframe from a Next.js App Router app — the Next
+ * counterpart to `viteDevBridge`, reduced to memoization + defaults over
+ * `initDevframe` (Next's route handlers can't accept WS upgrades, so the
+ * RPC socket lives on the instance's side-car port, advertised at
+ * `<base>__connection.json`).
  *
- * ```ts [app/__my-tool/[[...path]]/route.ts]
+ * ```ts [app/%5F_my-tool/[[...path]]/route.ts]
  * import myDevframe from '@/devframe'
  * import { createDevframeNextHandler } from '@devframes/next'
  *
@@ -101,7 +104,7 @@ interface DevframeNextHandler {
  * export const GET = handler.fetch
  * ```
  *
- * For a hub hosting many devframes at once, use {@link createDevframeNextHost}
+ * For a hub hosting many devframes at once, use `createDevframeNextHost`
  * directly with `@devframes/hub`.
  */
 declare function createDevframeNextHandler(def: DevframeDefinition, options?: CreateDevframeNextHandlerOptions): DevframeNextHandler;

package/dist/index.mjs

@@ -1,8 +1,8 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import process from "node:process";
-import { createDevServer, resolveDevServerPort, resolveMcpConnectionMeta } from "devframe/adapters/dev";
-import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_WS_ROUTE } from "devframe/constants";
+import { initDevframe } from "devframe/initiate";
+import { DEVFRAME_CONNECTION_META_FILENAME } from "devframe/constants";
 import { serveStaticHandler } from "devframe/utils/serve-static";
 import { H3 } from "h3";
 //#region src/config.ts
@@ -31,6 +31,80 @@ function withDevframe(nextConfig = {}) {
 	};
 }
 //#endregion
+//#region src/handler.ts
+/** Ensure a mount base has a single leading and trailing slash. */
+function normalizeBase(base) {
+	return `/${base}/`.replace(/\/{2,}/g, "/");
+}
+const REGISTRY_KEY = Symbol.for("@devframes/next:handler-registry");
+/**
+* Handlers memoized per key on `globalThis`. Next re-evaluates route modules
+* on every dev-time reload, so without this each reload would start a fresh
+* side-car WebSocket server and leak the previous one.
+*/
+function handlerRegistry() {
+	const holder = globalThis;
+	holder[REGISTRY_KEY] ??= /* @__PURE__ */ new Map();
+	return holder[REGISTRY_KEY];
+}
+function defaultGetStorageDir(scope) {
+	const cwd = process.cwd();
+	if (scope === "workspace") return join(cwd, ".devframe");
+	if (scope === "project") return join(cwd, "node_modules/.devframe");
+	return join(homedir(), ".devframe");
+}
+/**
+* Host a **single** devframe from a Next.js App Router app — the Next
+* counterpart to `viteDevBridge`, reduced to memoization + defaults over
+* `initDevframe` (Next's route handlers can't accept WS upgrades, so the
+* RPC socket lives on the instance's side-car port, advertised at
+* `<base>__connection.json`).
+*
+* ```ts [app/%5F_my-tool/[[...path]]/route.ts]
+* import myDevframe from '@/devframe'
+* import { createDevframeNextHandler } from '@devframes/next'
+*
+* export const runtime = 'nodejs'
+* export const dynamic = 'force-dynamic'
+*
+* const handler = createDevframeNextHandler(myDevframe)
+* export const GET = handler.fetch
+* ```
+*
+* For a hub hosting many devframes at once, use `createDevframeNextHost`
+* directly with `@devframes/hub`.
+*/
+function createDevframeNextHandler(def, options = {}) {
+	const distDir = def.cli?.distDir;
+	if (!distDir) throw new Error(`[@devframes/next] createDevframeNextHandler("${def.id}") needs a built SPA to serve, but "cli.distDir" is not set on the devframe definition.`);
+	const base = normalizeBase(options.base ?? def.basePath ?? `/__${def.id}/`);
+	const key = options.key ?? `@devframes/next:${def.id}:${base}`;
+	const registry = handlerRegistry();
+	const memoized = registry.get(key);
+	if (memoized) return memoized;
+	const instance = initDevframe(def, {
+		base,
+		distDir,
+		host: options.host,
+		flags: options.flags,
+		auth: options.auth,
+		mcp: options.mcp,
+		ws: options.port != null ? { port: options.port } : { sidecar: true },
+		...options.resolveOrigin ? { origin: options.resolveOrigin } : {},
+		getStorageDir: options.getStorageDir ?? defaultGetStorageDir
+	});
+	const handler = {
+		fetch: (request) => instance.handler(request),
+		ready: instance.ready,
+		close: async () => {
+			if (registry.get(key) === handler) registry.delete(key);
+			await instance.close();
+		}
+	};
+	registry.set(key, handler);
+	return handler;
+}
+//#endregion
 //#region src/host.ts
 const META_SUFFIX = `/${DEVFRAME_CONNECTION_META_FILENAME}`;
 /** Drop trailing slashes from a mount base (`/__git/` → `/__git`). */
@@ -105,84 +179,4 @@ function createDevframeNextHost(options) {
 	};
 }
 //#endregion
-//#region src/handler.ts
-/** Ensure a mount base has a single leading and trailing slash. */
-function normalizeBase(base) {
-	return `/${base}/`.replace(/\/{2,}/g, "/");
-}
-function defaultGetStorageDir(scope) {
-	const cwd = process.cwd();
-	if (scope === "workspace") return join(cwd, ".devframe");
-	if (scope === "project") return join(cwd, "node_modules/.devframe");
-	return join(homedir(), ".devframe");
-}
-/**
-* Host a **single** devframe from a Next.js App Router app — the convenience
-* wrapper over {@link createDevframeNextHost} for the common case of mounting
-* one plugin (the Next counterpart to `viteDevBridge`'s bridge mode).
-*
-* It statically serves `def.cli.distDir` at `base` through the Next route and
-* starts a side-car RPC/WS dev server (via `createDevServer` in bridge mode) on
-* its own port, advertising that endpoint at `<base>/__connection.json` so the
-* SPA's `connectDevframe()` can dial back in.
-*
-* ```ts [app/__my-tool/[[...path]]/route.ts]
-* import myDevframe from '@/devframe'
-* import { createDevframeNextHandler } from '@devframes/next'
-*
-* export const runtime = 'nodejs'
-* export const dynamic = 'force-dynamic'
-*
-* const handler = createDevframeNextHandler(myDevframe)
-* export const GET = handler.fetch
-* ```
-*
-* For a hub hosting many devframes at once, use {@link createDevframeNextHost}
-* directly with `@devframes/hub`.
-*/
-function createDevframeNextHandler(def, options = {}) {
-	const distDir = def.cli?.distDir;
-	if (!distDir) throw new Error(`[@devframes/next] createDevframeNextHandler("${def.id}") needs a built SPA to serve, but "cli.distDir" is not set on the devframe definition.`);
-	const base = normalizeBase(options.base ?? def.basePath ?? `/__${def.id}/`);
-	const hostName = options.host ?? def.cli?.host;
-	const nextHost = createDevframeNextHost({
-		resolveOrigin: options.resolveOrigin ?? (() => ""),
-		getStorageDir: options.getStorageDir ?? defaultGetStorageDir
-	});
-	nextHost.host.mountStatic(base, distDir);
-	nextHost.host.mountConnectionMeta?.(base);
-	let started;
-	const ready = (async () => {
-		const port = options.port ?? await resolveDevServerPort(def, { host: hostName });
-		started = await createDevServer(def, {
-			host: hostName,
-			port,
-			flags: options.flags,
-			openBrowser: false,
-			auth: options.auth,
-			mcp: options.mcp
-		});
-		const mcpMeta = resolveMcpConnectionMeta(def, options.mcp, port);
-		nextHost.setConnectionMeta({
-			backend: "websocket",
-			websocket: {
-				port,
-				path: `/${DEVFRAME_WS_ROUTE}`
-			},
-			...mcpMeta ? { mcp: mcpMeta } : {}
-		});
-	})();
-	return {
-		async fetch(request) {
-			await ready;
-			return nextHost.fetch(request);
-		},
-		ready,
-		async close() {
-			await ready.catch(() => {});
-			await started?.close();
-		}
-	};
-}
-//#endregion
 export { createDevframeNextHandler, createDevframeNextHost, withDevframe };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@devframes/next",
   "type": "module",
-  "version": "0.8.1",
-  "description": "Next.js host integration for Devframe — serve mounted devframe SPAs and connection meta from an App Router route (experimental)",
+  "version": "0.9.0-beta.1",
+  "description": "Next.js host integration that serves mounted devframes from an App Router route.",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
   "homepage": "https://github.com/devframes/devframe#readme",
@@ -37,7 +37,7 @@
   "peerDependencies": {
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
-    "devframe": "0.8.1"
+    "devframe": "0.9.0-beta.1"
   },
   "peerDependenciesMeta": {
     "next": {
@@ -51,11 +51,11 @@
     "h3": "^2.0.1-rc.26"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2",
-    "@types/react": "^19.2.17",
+    "@types/node": "^26.2.0",
+    "@types/react": "^19.2.18",
     "react": "^19.2.8",
     "tsdown": "^0.22.14",
-    "devframe": "0.8.1"
+    "devframe": "0.9.0-beta.1"
   },
   "scripts": {
     "build": "tsdown",